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(57) Abstract: An operating system (OS) services -to-peer networking connectivity adapter exposes services of a general purpose 
operating system to remote control via a peer networking device control protocol, which allows reuse of the operating system service 
without reprogramming ihe service as a "controlled device" per the peer networking device control protocol. The adapter includes a 
publishing service that implements components of a controlled device and operates to emulate a set of controlled devices that expose 
the functionality of the OS services. A service remoter converts between a publishing application programming interface (API) of 
the publishing service and the established operating system API of the OS services. 
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REMOTING GENERAL PURPOSE OPERATING SYSTEM SERVICES VIA A 
PEER NETWORKING DEVICE CONTROL PROTOCOL 

TECHNICAL FIELD 

This invention relates generally to remote access to and control of 
5 general purpose operating system services, and more particularly to 
remoting such services via a peer networking device control protocol. 

BACKGROUND AND SUMMARY 

Present day, general purpose operating systems provide numerous 
services for use by application programs. An operating system is software 

1 0 that generally controls the allocation and usage of hardware resources on a 
computer, such as memory, central processing unit (CPU) time, disk space, 
and peripheral devices. General purpose operating systems provide an 
operating platform or environment on which application software for a wide 
variety of purposes can be run. Examples of popular general purpose 

15 operating systems include Microsoft Windows operating systems (e.g., 
Windows 95, 98, NT, 2000); the Mac OS of Apple Computer, Inc.; UNIX 
or Linux available from various vendors; and BeOS from Be, Inc. 

A service has generally been defined to be a program, routine, or 
process that performs a specific system function to support other 

20 programs, particularly at a low (close to the hardware) level. Typically 

although not necessarily, the services do not provide a user interface (Ul) 
or interact directly with the user (e.g., display messages in a window or 
dialog box, or receive input from keyboard or mouse) during normal 
processing (except error messages and like interaction when exceptions 

25 occur, and administration or configuration of the service), but instead 
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typically operate under programmatic control of an application program 
with which the user directly interacts. Examples of services provided in 
the Microsoft Windows® operating systems include date and time clock, file 
and printer sharing, print spooling, electronic mail, fax, telephony, file 
5 synchronization (e.g., with mobile devices), file backup and archiving, audio 
and video file streaming (e.g., to a peripheral play-back device, such as 
speakers or a monitor), audio and video codecs, file 

compression/decompression, problem diagnosis and support, event logging, 
user and software configuration administration, security and access 

10 control, remote access (RAS), networking (Internet socket, FTP, HTTP, 

TCP/IP, NetBIOS, etc.), name and address (DHCP, DNS), remote procedure 
call (RPC) and named pipe, dynamic peripheral configuration (Plug and 
Play), and application scheduling (e.g., Windows 95 system agent), among 
others. In addition to the services provided with an operating system by its 

1 5 vendor, some operating systems (e.g., Microsoft Windows NT) also 
support an extendible services architecture that permits plugging in or 
installing later-developed services (e.g., Windows NT Services, Unix 
Daemon). 

Operating system services typically are exposed for programmatic 
20 control and use by locally executing application programs through an 
application programming interface (API) of the operating system. The 
application program typically provides a user interface with which the user 
interacts to effect application-specific task work. The application program 
may utilize the operating system services, and programmatically -controls 
25 the services through the APIs. For example, a "music jukebox" application 
program could provide a user interface having a "graphics equalizer" and 
"playlist" display, and start, stop and pause controls with which the user 
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interacts to play music audio files. The application program, in turn, 
utilizes audio streaming services of the operating system, which the 
application program controls via an API. The operating system API 

typically operates using a local procedure call, software interrupt, or like 
5 mechanism. 

Present industry trends (e.g., rapidly decreasing costs of computing 
and networking technologies) are leading towards embedding -computing 
and networking capabilities into the design of many specific-purpose 

♦ 

devices in the home, office and public places. Examples include digital 

10 cameras; audio/video receivers, recorders and players; printers; home 
appliances; lighting systems; heating, ventilation and air-conditioning 
(HVAC) equipment; security systems; telephony equipment; and etc. The 
combination of inexpensive and reliable shared networking media with a 
new class of small computing devices has created an opportunity ior new 

1 5 functionality based mainly on the connectivity among these devices. This 
connectivity can be used to remotely control devices, to move digital data 
in the form of audio, video and still images between devices, to share 
information among devices and with the Internet and to exchange 
structured and secure digital data to support things like electronic 

20 commerce. The connectivity also enables many new applications for 
computing devices, such as proximity-based usage scenarios where 
devices interact based at least in part on geographical or other notions of 
proximity. These developments are occurring at the same time as more 
people are becoming connected to the Internet and as connectivity 

25 solutions are falling in price and increasing in speed. These trends appear 
to lead towards a world of ubiquitous and pervasive networked computing, 
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where computing and networking are built into all types of devices in the 
user's home, work and public environments. 

With pervasive networked computing, the general use scenario 
changes from one where the user interacts directly with a device that 
5 performs some work (e.g., by pressing buttons on a control panel), to one 
where the user interacts with one device that provides user interactivity 
and remotely controls another device doing the work. For example, the 

user directly interacts with a universal remote controller, cell phone or 

• ' -I 

handheld/palm top/tablet computer to operationally control other devices in 

10 their immediate environment, such as a vending machine, video monitor, 
printer, door opener, or etc. 

Recently, several peer networking device control protocols have been 
introduced to support this new remote control use scenario expected to 
become typical of pervasive computing. These include the Home Audio 

1 5 Video Interoperability (HAVi) protocol developed by thie Havi Organization 
(formed by Grundig AG, Hitachi, Ltd., Matsushita Electric Industrial Co., 
Ltd. (Panasonic), Royal Philips Electronics, SharpKIorp., Sony Corp., 
Thomson Multimedia and Toshiba Corp); the JINI protocol developed by 
Sun Microsystems, Inc.; and the Universal Plug and Play (UPnP) protocol of 

20 the UPnP Forum and Microsoft Corporation. In general, these peer 
networking device control protocols are designed to allow devices to 
expose their operational functionality to remote control from devices 
directly operated by a user. 

As discussed above, general purpose operating systems provide a 

25 rich set of services to application programs running on the operating 
system via locally accessible APIs. In pervasive computing, peer 
networking device control protocols allow remote control of operational 

4 
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functionality of typically specific purpose devices. It would generally be 
advantageous to also remotely control the general purpose operating 
system services in pervasive computing environments. However, because 
the services are programmed to be exposed through the operating system 
5 APIs and not via peer networking device control protocols, the services are 
not available to user control devices through these protocols. 

In the UPnP protocol, legacy peripheral devices (e.g., scanner, 
printers, data storage drives, etc.) connected to a host computer can be 
exposed for remote control from a "user control point" device via a "UPnP 

10 bridge," which acts as a converter or adapter between the UPnP peer 
networking connectivity protocol and a host-peripheral connectivity 
protocol. The UPnP bridge generally runs on the host computer acting as a 
controlled device in place of a "bridged peripheral device" to respond to 
addressing, discovery, description, and control messaging in the UPnP 

1 5 protocol from user control point devices, and in turn interacts accordingly 
with the bridged peripheral device using the bridged peripheral's host- 
peripheral connectivity protocol. Again however, because general purpose 
operating system services are programmed to be exposed through 
operating system APIs, the services are not available to remote control via 

20 a UPnP bridge to a host-peripheral connectivity protocol. 

The present invention provides a way to expose general purpose 
operating system services to remote control via a peer networking device 
control protocol, which allows reuse of the operating system service 
without reprogramming the service as a "controlled device" per the peer 

25 networking device control protocol. In accordance with the invention, an 
adapter runs on the general purpose operating system and converts 
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between the peer networking device control protocol and operating system 
APIs, so as to remote the general purpose operating system's services. 

In an implementation of the invention described herein, the adapter 
includes a publishing service and a service remoter. The service remoter 
5 operates to remote operational functionality of general purpose operating 
system services through the publishing service. The publishing service 
supports a publishing API via which application programs running on the 

operating system as well as the service remoter can interact with the 

I. 

publishing service. The publishing service operates to expose operational 
1 0 functionality of the application programs and the services that interact with 
the publishing service through the publishing API as "controlled devices" 
under the peer networking device control protocol. The publishing service 
acts as the "controlled devices" per the peer networking device control 
protocol by appropriately responding on behalf of the remoted applications 
15 and services to addressing, discovery, description and control requests 
made by user control point devices in the peer networking device control 
protocol. The publishing service further converts these peer networking 
device control protocol requests to cause appropriate controlled operation 
of the services through the service remoter, which in turn interacts directly 
20 with the services through their APIs to effect the controlled operation. 

* * ■ ■ » 

Additional features and advantages will be made apparent from the 
following detailed description of the illustrated embodiment which proceeds 
with reference to the accompanying drawings. 

* 

BRIEF DESCRIPTION OF THE DRAWINGS 

25 Figures 1 and 2 are block diagrams of a device architecture per 

Universal Plug and Play using user control points, controlled devices, 
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bridges, and service remoter/publisher for connectivity between devices 
and services. 

Figure 3 is a block diagram of a general purpose operating system 
architecture with service remoter/publisher for remoting operating system 
5 services per Universal Plug and Play in accordance with an implementation 
of the invention. 

Figure 4 is a block diagram of an implementation of the service 
remoter/publisher of Figure 3 in the Microsoft Windows operating system 
architecture. 

1 0 Figure 5 is a block diagram of a device model per Universal Plug and 

Play. 

Figure 6 is a block diagram illustrating example devices -conforming 
to the device model of Figure 5. 

Figure 7 is a block diagram illustrating device state synchronization 
1 5 using a state table and eventing. 

Figure 8 is a block diagram illustrating device addressing. 
Figure 9 is a block diagram of a programmatic interface-to-network 
messaging adapter or Rehydrator in the device control model of Figure 5. 
Figure 10 is a general data flow diagram of the Rehydrator of Figure 
20 9 in the device control model of Figure 5. 

Figure 11 is a block diagram of an implementation design of the 
Rehydrator of Figure 9. 

Figures 1 2 and 1 3 are block diagrams illustrating an internal software 
architecture of the user control point and controlled device in the device 
25 control model of Figure 5. 
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Figure 14 is a block diagram illustrating an internal software 
architecture of a combined bridge and user control point in the device 
control model of Figure 5. 

Figure 15 is a data flow diagram illustrating a typical browsing 
5 protocol sequence in the device control model of Figure 5. 

Figure 1 6 is a listing showing a layout of a description document in 
the device control model of Figure 5. 

Figure 17 is a listing. of an exemplary icon list of a Description 
Document in the device control model of Figure 5. 
10 Figure 18 is a listing of an exemplary service control protocol 

declaration in a Description Document in the device control model of Figure 
5. 

Figures 1 9 and 20 are a listing of an XML schema for a Service 
Control Protocol Declaration Language used in the device control model of 
15 Figures. 

Figure 21 is a block diagram of an eventing model used in the device 
control model of Figure 5. 

Figure 22 is a data flow diagram illustrating subscription, notification 
and unsubscription in the eventing model of Figure 21 . 
20 Figure 23 is a block diagram of a computer system that may be used 

in the device control model of Figure 5. 

Figure 24 is a block diagram of a device having embedded computing 
and networking capability per untversal-plug-and-play (UPnP) standards that 
may be used in combination with the computer system of Figure 23 in the 
25 device control model of Figure 5. 

Figure 25 is a block diagram of a software architecture per UPnP 
standards in the embedded computing device of Figure 24 

8 
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Figure 26 is a data flow diagram of a process for automatic network 
introduction of the embedded computing device of Figure 24 into an ad hoc 
computer network environment per the UPnP protocol. 

Figure 27 is a data flow diagram of a process for automatic network 
5 introduction of the embedded computing device of Figure 24 into a 
configured computer network environment per the UPnP protocol. 

Figure 28 is a block diagram of a software architecture of a client 
device per UPnP standards having embedded computing and networking 
capability that may be used in the device control model of Figure 5. 
10 Figure 29 is a block diagram of an exemplary home or office 

pervasive computing environment having a variety of computers as per 
Figure 23 and embedded computing devices as per Figure 24 
interconnected per UPnP standards that may be used in the device control 
model of Figure 5. 

1 5 Figures 30 through 40 are program listings of interfaces used in the 

Rehydrator implementation design of Figure 11. 

Figure 41 is a flow diagram illustrating automatically installing and 
configuring a UPnP bridge upon attaching or connecting a peripheral on a 
host personal computer. 

20 

DETAILED DESCRIPTION 

The following detailed description is directed toward adapting 
general purpose operating system (OS) services for operation within a 
distributed device control model having peer networking connectivity. In 
25 one described implementation, this OS service-to-peer networking control 
protocol adapter is used in a device architecture 100 (Figure 1), 
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connectivity model, and device control protocol proposed by Microsoft 
Corporation, called Universal Plug and Play ("UPnP"). 

Universal Plug and Play 

Universal Plug and Play (UPnP) is an open network architecture that 
5 is designed to enable simple, ad hoc communication among distributed 
devices and services from many vendors. UPnP leverages Internet 
technology and can be thought of as an extension of the Web model of 
mobile Web browsers talking to fixed Web servers to the world of peer-to- 
peer connectivity among mobile and fixed devices. UPnP embraces the 

1 0 zero configuration mantra of Plug and Play (PnP) but is not a simple 
extension of the PnP host/peripheral model. 

The cost, size and battery consumption of computing technology- 
including processing, storage and displays-continues to fall. This trend is 
enabling the evolution of stand-alone, single or limited function computing 

15 devices such as digital cameras, audio playback devices, smart mobile 
phones and handheld computers. Concurrent with this, the economical 
storage and transmission of digital audio, video and still images is enabling 
highly flexible models for managing entertainment content. 

While many of these devices are capable of useful stand-alone 

20 operation, seamless connectivity with the PC can enhance the value to the 
customer of both stand-alone devices and the PC. X3ood examples of this 
synergy are digital image capture combined with PC image manipulation, 
storage and email transfer/Web publishing and information synchronization 
between a PC and a handheld computer or smart mobile phone. 

« 

25 Since many of these devices, and the PC itself, are mobile, a suitable 

communication architecture must enable a highly dynamic connectivity 
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model and must enable peer-to-peer interoperability among arbitrary 
combinations of devices. 

The Internet has created a widespread awareness of the value of 
simple, universal communication that is independent of the underlying 
5 transmission technology and independent of technology from any single 
vendor. 

UPnP makes it possible to initiate and control the transfer of bulk 
data (e.g. files) or A/V data streams from any device on the network, to 
any device on the network, under the control of any device on the 
1 0 network. UPnP enables the ad hoc addition or removal of devices on the 
network, and it enables multiple controlling devices to remain in sync with 
each other. 

UPnP reuses existing protocols and technology whenever possible. 
The transition to this highly connected {and connectable) world will not 

1 5 occur overnight. UPnP builds on existing Internet protocols, but 

accommodates devices that cannot run the complete UPnP protocol suite. 
UPnP provides an architecture that enables legacy devices to communicate 
with UPnP devices. 

IP internetworking has been chosen as a UPnP baseline due to its 

20 proven ability to span different physical media, to enable real world multiple 
vendor intieroperation and to achieve synergy with the Internet and home 
and office intranets. Internet synergy enables applications such as IP 
telephony, multiple player games, remote control of home automation and 
security, Internet based electronic commerce, in addition to simple email 

25 and Web browsing. UPnP's scope includes remote control of devices and 
bulk data transfer, and can be easily extended to specify A/V streaming. 

11 
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UPnP's media independence enables a great deal of flexibility in the 
packaging of products. UPnP enables an A/V system to be controlled 
through an A/C power communications technology, while the transmission 
of A/V streams among the components is analog or digital. One of the 
5 controllers of this system could be on the television, while another is on a 
PC, aind yet another connected via radio or infrared. 

Unlike Plug and Play, Universal Plug and Play is built on top of 
networking and enables ad hoc peer-to-peer connectivity. Networking, in 
this context, describes a style of connectivity t!hat enables any networked 

1 0 device to initiate a communication with any other networked device, 

without having established a prior relationship or maintaining a persistent 
relationship between the devices. Networking also allows multiple devices 
to establish one or more connections with a single device, and it allows for 
a device to be capable of both initiating and accepting connections to /from 

1 5 other devices. The PnP, or host/peripheral, model is suitable whenever 
there is a natural persistent relationship between two devices (e.g. a 
keyboard, mouse and display maintain a persistent relationship with a host 
computer). Even though networking does not mandate low level persistent 
relationships, it provides the needed anchors (addresses) for applications to 

20 choose to maintain associations as a convenience for the customer (e.g. 
remembering commonly used networked printers). 

In order to achieve multiple vendor peer-to-peer interoperation among 
devices, vendors desirably agree on common technology and standards up 
to the highest level of desired functional interoperation. 

25 UPnP leverages formal protocol contracts to enable peer-to-peer 

interoperation. Protocols contracts enable real-world multiple-vendor 
interoperation. 

12 
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UPnP enables devices to expose a user interface by leveraging 
browser technology. In this context, the browser can be considered to be 
a very rich remote terminal. Current browser technology does not maintain 
a separation of presentation from data, or in the case of devices, control. 
5 It is possible to hunt through a page of HTML to extract data values, but it 
is not convenient or robust. UPnP leverages the separation of presentation 
and data enabled by the use of XML, and it extends this technology to the 
device control domain. 

UPnP provides a device-driven auto-configuration capability that 
10 preserves the experience that customers have on the Web, Today, it is 

possible to navigate around the Web without loading programs beyond the 
browser itself. Since UPnP enables the browser to be extended to control 
devices, and because UPnP devices are controlled with explicit protocols, 
the browser must somehow learn how to talk to UPnP devices. This 
1 5 learning process is driven entirely from the device itself and is 

* 

accomplishing entirely by uploading an XML document that describes the 
capabilities of the device. The architectural component that enables 
device-driven auto-configuration is called the Rehydrator. The job of the 
Rehydrator is to convert between APIs and protocols. 

20 Since the auto-configuration process itself is driven only by the 

exchange of formatted data, there is very little opportunity for a malicious 
attack from a hostile piece of code. 

There are some scenarios where the Web Ul model is not sufficient 
for a rich customer experience. It would not be convenient to have to a 

25 separate Web Ul for each light switch in a house. To support a rich user 
interface and to enable the aggregation of devices into a single Ul, UPnP 
enables application control in addition to browser control of devices. This 
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is achieved simply by enabling applications to call the same Rehydrator 
APIs that the browser does. Applications can also directly generate and 
consume the raw UPnP control protocols, provided they are not interested 
in the device-driven auto-configuration enabled by the Rehydrator. 
5 UPnP assumes that there will be more than one device with U I that 

wants to control other devices in any given network, and it provides a 
simple mechanism that enables these control points to remain in sync. 
This mechanism can easily support device front panels and wireless 
remotes that do not run UPnP protocols. The UPnP control model is third- 
10 party control; any device can transfer bulk data (e.g. files) or A/V data 
streams from any device on the network, to any device on the network, 
under the control of any device on the network. 

Terminology 

The detailed description that follows uses the terminology defined 

1 5 below. 

Module . A component of a device, software program, or system 
that implements some "functionality", which can be embodied as software, 
hardware, firmware, electronic circuitry, or etc. 

. - 

User Control Point . The set of modules that enable communication 
20 with a UPnP Controlled Device. User Control Points initiate discovery and 
communication with Controlled Devices, and receive Events from 
Controlled Devices. User Control Points are typically implemented on 
devices that have a user interface. This user interface is used to interact 
with Controlled Devices over the network. The modules minimally include 
25 a Discovery Client, a Description Client, a Rehydrator, an Event 

Subscription Client and an Event Sink. User Control Points may also 
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include Visual Navigation, a Web browser and an application execution 
environment. User Control Points can add value to the network by 
aggregating the control of multiple Controlled Devices (the universal 
remote) or they can implement a function as simple as initiating the 
5 transfer of data to or from a Controlled Device. Examples of devices that 
could be User Control Points are the personal computer {PC), digital 
television (DTV), set-top box {STB), handheld computer and smart mobile 
phone, and the like. Nothing prevents a single device from implementing 
the functionality of a User Control Point and one or more Controlled 
10 Devices at the same time. 

Controlled Device . The set of modules that perform certain tasks 
(e.g., printing) and communicate with a User Control Point. Controlled 
Devices respond to discovery requests, accept incoming communications 
from User Control Points and may send Events to User Control Points. 

1 5 Devices that support Controlled Device functionality may also support local 
user interfaces such as front panel displays or wireless remotes. The 
modules minimally include a Discovery Server, a Description Server, a. 
Control Server, an Event- Subscription Server and an Event Source. 
Controlled Devices may also include a Presentation (e.g., Web) Server. 

20 Examples of devices that could be Controlled Devices are the VCR, DVO 
player or recorder, heating/ventilation/air-conditioning equipment (HVAC), 
lighting controller, audio/video/imaging playback device, handheld 
computer, smart mobile phone and the PC, and the like. Nothing prevents 
a single device from implementing the functionality of a User Control Point 

25 and one or more Controlled Devices at the same time. 
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Bridge . A set of modules that enables Bridged and Legacy Devices 
to interact with native UPnP devices. The bridge itself exposes a collection 
of UPnP Controlled Devices to User Control Points. The Bridge maps 
between native UPnP Device Control Protocols and the underlying protocols 
5 or other control methods exposed by the Bridged and Legacy Devices. 

Optionally, such a device could expose UPnP Controlled Devices to Legacy 
Devices in the manner required by the Legacy Devices. Nothing prevents a 
single device from implementing the functionality of a User Control Point, 
one or more Controlled Devices and a Bridge at the same time. 

10 Service Provider . A module used by a UPnP Bridge that translates 

between UPnP protocols and the protocols used by Bridged and Legacy 
Devices. No Service Providers are required for communication among 
native UPnP devices. 

Bridged Device . A device that cannot participate in UPnP at the 
1 5 native protocol level, either because the device does not have sufficient 
resources or because the underlying media is unsuitable to run TCP and 
HTTP. Examples of devices that could be Bridged Devices are power line- 
controlled A/V equipment, light switches, thermostats, wristwatches and 
inexpensive toys. Bridged Devices are UPnP complaint and are exposed to 
20 other UPnP devices through a UPnP Bridge. 

Legacy Device . Any non-UPnP compliant device that must be 
exposed to other UPnP devices through a UPnP Bridge. 

Device Model . The UPnP model of Controlled Devices. The Device 
Model includes the addressing schemes, Description Document, Devices 
25 and Services hierarchy and the functional description of Services. 
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Device Control Protocol (DCP) . A complete set of UPnP protocols 
and schemas used to interact with a UPnP Controlled Device. 

Device Definition . The formal definition of a Device Type. A Device 
Definition includes a Device Type Identifier, the fixed elements in the 
5 Description Document, the required set of Service Definitions in the Root 
Device, and the hierarchy of required Devices and Service Definitions. 

Service Definition . The formal definition of a Service Type. A 
Service Definition includes a Service Type Identifier, definition of the 
Service State Table (SST), definition of the Service Command Set, the 
1 0 Service Control Protocol (SCP) and Service Control Protocol Declaration 
(SCPD). 

Device . In the context of the Device Model, a container for Services. 
A Device generally models a physical entity such as a VCR, but can also 
represent a logical entity. A PC emulating the traditional functions of a 
1 5 VCR would be an example of a logical device. Devices can contain other 
Devices. An example would be a TV/ VCR packaged into a single physical 
unit. UPnP enables the association of user interface (display icon and root 
Web page) with every Device, including Root Device. 

• * * 

Root Device . The topmost Device in a hierarchy of nested Devices. 
20 A Device with no nested Devices is always a Root Device. 

Device Type . A relatively high level classification of Devices with 
common functionality. Device Type is intended to enable Devices to be 
simply and automatically grouped for search and/or presentation. An 
example of a Device Type is "VCR". Device Types are formally defined in 
25 terms of a required set of Service Definitions of minimum version that a 
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compliant Device must support. UPnP supports searches for all Devices of 
a specified Device Type. 

Device Type Identifier . A unique identifier that identifies a Device 
Definition. This identifier adheres to the format of a Uniform Resource 
5 Identifier (URI). See, T. Berners-Lee, R. Fielding, L. Masinter, Uniform 

Resource Identifiers (URI): Generic Syntax , IETF RFC 2396 (August 1998). 

Device Friendly Name . A human readable string that is usually 
initialized by vendors at the time of manufacturer of a Device. Every 
Device, including Root Devices, has a Device Friendly Name. A typical 

10 Device Friendly Name will contain manufacturer and model information, and 
especially when interpreted by humans, can be used to enable a more 
precise identification of a UPnP Device from the set of discovered Devices. 
Once identified, the Unique Device Name (UDN) can be used to 
unambiguously identify the same Device in the future. UPnP enables 

1 5 Device Friendly Names to be changed by User Control Points. The Device 
Friendly Name should not be used as device identifier. 

Unique Device Name (UDN) . The fundamental identifier of a Device. 
Every Device, including Root Devices, has exactly one UDN. The UDN is 
globally unique and permanent, even across power cycles and physical 

* 

20 location changes. The UDN is the only UPnP device identifier guaranteed 
never to change. UPnP enables searches for devices by UDN. 

Description Document . A structured unit of data that is used by a 
User Control Point or UPnP Bridge to learn the capabilities of a Controlled 
Device. Description Documents are retrieved from the Description Server 
25 on a UPnP Controlled Device. There is one Description Document for every 
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Root Device that describes the Root Device and all non-Root Devices. 
Description Documents adhere to XML grammar. To support localization; 
multiple Description Documents can exist. A User Control Point requests 
the preferred localized Description Document by using the standard 4HTTP 
5 "accept-language" header. 

Service . The fundamental UPnP controllable entity (but not the 
finest level of control). An example of a -Service is "Clock". Services are 
defined with a mandatory common base set of functionality. Vendors can 
extend the base set with proprietary extensions provided the base 

10 functionality is implemented. Service Definitions are versioned and later 
versions are constrained to be supersets of previous versions. UPnP 
enables searches for all Devices that contain a specified Service of a 
minimum version. This search would find all clocks, regardless of their 
packaging. A search for Device Type "Clock" would be used to find only 

15 stand-alone clocks. 

Service Type . A classification of Services by their function. 

Service Type Identifier . A unique identifier that identifies a Service 
Definition. This identifier adheres to the format of a Uniform Resource 
Identifier (URI). See, T. Berners-Lee, R. Fielding, L. Masinter, Uniform 
20 Resource Identifiers (URI): Generic Syntax / IETF RFC 2396 (August 1998). 

Service State Table (SST) . A logical table consisting of rows of [ 
Variable, Type, Legal Values, Default Value, Current Value ] that represents 
the current electrical, mechanical and/or logical state of a Service. SST 
instances are stored on the Controlled Device itself and are the ultimate 
25 authority of the state of the Service. All local user interface, such as front 
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panels or wireless remotes are required to update the SST on UPnP 
compliant devices. 

SST Definition: 

♦ • 

Service Command Set . A set of Commands that can be invoked on 
5 a Service. Commands generally result in changes in the Current Value field 
of one or more rows of a SST. Commands are logically represented in the 
format Command ( Variable = New Value, Variable = New Value, ... ). 
Services must accept or reject the complete set of changes to a SST. 
There is a mandatory istandard Query Command that is used to retrieve the 
10 Current Value of any row of a SST. 

Service Command Set Definition: 

Service Control Protocol (SCP) . The protocol used to invoke 
Commands against a Service and to return results. There is exactly one 
SCP per Service Definition. SCPs adhere to the grammar of SCP XML 
15 schema. SCPs can be generated by an automated tool that accepts a SST 
Definition and a Command Set Definition as input. 

Service Control Protocol Declaration (SCPD) . A formal 
representation of the schema of a Service. The SCPD declares the rows of 
a Service's SST and the associated Command Set. SCPDs are uploaded 

20 from Controlling Devices in their Description Documents and enable User 
Control Points or Bridges to invoke Commands on the Service without any 
prior or persistent knowledge of the capabilities (or schema) of the Service. 
There is exactly one SCPD per Service Definition. SCPDs adhere to XML 
grammar. SCPDs can be generated by an automated tool that accepts a 

25 SST Definition and a Command Set Definition as input. 

* 
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Event . An unsolicited message generated by a Controlled Device 
and delivered to one or more User Control Points. Events are used to 
maintain a consistent view of the state of Service across all interested User 
Control Points. UPnP leverages the GENA event architecture (see "Generic 
5 Event Notification") to transport event messages. All events are delivered 
using TCP/IP for reliability. 

Generic Event Notification Architecture {GENA) . An event transport 
protocol. GENA leverages TCP/HTTP as a transport. GENA has been 
submitted as an Internet Draft to the IETF. See, J. Cohen, S. Aggarwal, Y. 
10 Goland, General Event Notification Architecture Base: Client to Arbiter , 
IETF Internet Draft, "draft-cohen-gena-client-OOitxt." 

Simple Service Discovery Protocol (SSDP) . A simple network device 
discovery protocol. UPnP uses SSDP to allow User Control Points to find 
Controlled Devices and Services. SSDP operates in a default, completely 

15 automatic multicast UDP/IP based mode in addition to a server-based mode 
that uses TCP/IP for registrations and query. Transitions between the 
default dynamic mode and server-based mode are automatic and 
transparent to upper level software. SSDP enables every Controlled Device 
to control the lifetime that its Description URL is cached in all User Control 

20 Points. This enables a Controlled Device to remain visible to User Control 
Points for a relatively long time (through power cycles), in addition to 
enabling a Controlled Device to appear and disappear very quickly, all under 
the control of the Controlled Device. SSDP and related Multicast and 
Unicast UDP HTTP Messages specifications have been submitted as 

25 Internet Drafts to the IETF. See, Y. Goland, Multicast and Unicast UDP 

HTTP Messages , IETF Internet Draft, "draft-goland-http-udp~OO.txt;" and Y. 
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Goland, T. Cai, P. Leach., Y, Gu, S. Albright, Simple Service Discovery 
Protocol/ 1.0 f IETF Internet Draft, "draft-cai-ssdp-v1-02.txt." 

Client . In the context of UPnP, Client refers to a module that 
initiates a TCP/HTTP connection to a peer HTTP server. 

* 

5 Server . In the context of UPnP, Server refers to an HTTP server. 

This is a module that accepts incoming TCP/HTTP connections and either 
returns a Web page or forwards the payload data to another module. 
Client and Server describe only the direction of initiation of TCP/HTTP 
connections. There is no relationship between the low level -concepts of 
1 0 Client and Server and the high level concepts of User Control Point and 
Controlled Devices. Logically, User Control Points always discover and 
initiate communication with Controlled Devices, but this communication 

i - 

requires Client and Server functionality on both sides. 

Hostname . A Hostname is the Domain Name System (DNS) or 
15 NetBIOS Name Service (NBNS) that, when resolved to an IP address, 

represents a network interface that can be used to establish TCP/IP level 
connectivity to User Control Points, Controlled Devices or Bridges. 
Hostnames can be used to provide persistent network level addressing on a 
network where IP addresses are dynamically assigned and of unknown 
20 lifespan or to integrate with an existing managed network. UPnP provides 
an algorithm for seeding a device's hostname from its UDN at 
manufacturing time. 

Uniform Resource Locator (URL) . A format for expressing Web 
addresses. URLs minimally contain an identification of the protocol family 
25 that the URL is valid for, a Hostname, and a path. UPnP uses URLs as 
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addresses whenever the module accepting the incoming connection is an 
HTTP server. 

Description URL . The URL returned from a Controlled Device or 
Bridge in response to any UPnP SSDP query. This URL always points to a 
5 Description Server on the Controlled Device. An HTTP GET can be issued 
on this URL to retrieve the Description Document. This URL is valid as an 
address for the lifetime of the Hostname embedded in the URL. 

Discovery Server . The module that runs in a Controlled Device or 
Bridge that responds to SSDP queries. This Server is unique in that it must 
10 support UDP/HTTP in addition to TCP/HTTP. 

Discovery Client . The module that runs in a User Control Point that 
initiates SSDP queries. 

Description Server . The module that runs in a Controlled Device or 
Bridge that responds to HTTP GETs and returns Description Documents. 
1 5 This service consists of a TCP/HTTP server than can retrieve and return a 
Description Document from persistent storage (like a filesystem). 

Visual Navigation . User Control Point functionality that displays the 
icons of discovered Devices and enables the transfer of control to a 
browser or application to interact with the Controlled Device. In Windows, 
20 Visual Navigation could be implemented as a folder of icons. 

Presentation URL . A URL that can be used by a User Control Point 
to navigate to the Presentation Server of a Controlled Device. This URL is 
returned in the Description Document and is valid as an address for the 
lifetime of the Hostname embedded in the URL. All Devices, including non- 
25 Root Devices, can have an associated Presentation URL. 
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Presentation Server . A Web Server in most common cases. The 
module that runs in a Controlled Device that responds to HTTP<3ETs or 
Presentation URLs and returns user interface using Web technologies 
(JavaScript, Jscript®, ECMAScript, VBScript, ActiveX®, Java Applet, etc.). 

5 Browser . A Presentation Client. A Web browser extended with a 

Rehydrator. 

Control URL . A URL that can be used by a User Control Point to 
navigate to the Control Server of a Controlled iDevice or Bridge. This URL 
is returned in the Description Document and is valid as an address for the 
10 lifetime of the Hostname embedded in the URL. All Services have an 
associated Control URL. 

Control Server . The module that runs in a Controlled Device or 
Bridge that responds to Commands invoked on a Service by a User Control 
Point. Commands are encoded and sent using the SCP specified in the 
1 5 Service Definition. This service consists of a TCP/HTTP server that passes 
control to the native control logic of a Service, updates the SST and 
generates an event if the SST changes. 

Rehydrator . In UPnP, a Control Client. A User Control Point module 
that translates between native operating system APIs and SCPs and 
20 events. The Rehydrator uploads SCPDs from Controlled Devices and 
Bridges and generates appropriate SCPs in response to application API 
requests to invoke Commands. 

Event Subscription URL . A URL that can be used by a User Control 
Point to navigate to the Event Subscription Server of a Controlled Device or 
25 Bridge. This URL is returned in the Description Document and is valid as an 
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address for the lifetime of the Hostname embedded in the URL All 
Services have an associated Event Subscription URL. 

Event Subscription Server . The module that runs in a Controlled 
Device or Bridge that responds to<3EIMA SUBSCRIBE requests from User 
5 Control Points. A SUBSCRIBE informs the Controlled Device or Bridge of 
the User Control Point's desire to receive future events. This service 
consists of a TCP/HTTP server that adds the User Control Point's Event 
Sink URL to the list of destinations to be NOTIFY'd whenever the SST 
associated with the Service changes. 

1 0 Event Subscription Client . The module that runs in a User Control 

Point that sends GENA SUBSCIBE messages to the Event Subscription 
Server. 

Event Sink URL . A URL, supplied by a User Control Point, that is 
used as an address to send event NOTIFYs to. This URL is valid as an 

« ■ * 

1 5 address for the lifetime of the Hostname embedded in the URL. There is no 

T * « * 

explicit relationship between Event Sink URLs and Subscription Identifiers. 

Subscription Identifier (SID) . A header in the GENA NOTIFY 
message that identifies the source of an event. In UPnP, the SID can be 
considered as an alias for the Event Source instance. 

20 Event Sink . The module that runs in a User Control Point that 

accepts incoming GENA event NOTIFYs. This service consists of a 
TCP/HTTP server that passes the event information to interested 
applications running on the User Control Point. 
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Event Source . The module that runs in a Controlled Device or Bridge 
that sends GENA NOTIFYs to the Event Sink Servers of SUBSCRIBES User 
Control Points. 

Domain Name System (DNS) . A distributed system of servers that 
5 locates the IP addresses of other computers on a network based on their 
hierarchical names. 

NetBIOS Name Server (NBNS) . A server that locates the IP 
addresses of other computers on a network based on their flat NetBIOS 
computer names. 

1 0 Multicast DNS (MDNS) . A peer-to-peer translation scheme that does 

not require involvement of DNS servers. 

UPnP Technologies Overview 

An overview of technologies utilized in UPnP follows. 

Device Discovery: Simple Service Discovery Protocol (SSDP) 
15 TCP/IP provides the ability to initiate a connection with a specified 

application running on a specific device, provided both the network address 
of the device (IP address) and the application address (port) are known. 
Generally, application addresses (ports) are standardized and widely 
known, but the problem of learning the IP address of a device remains. 
20 Simple Service Discovery Protocol (SSDP) is a protocol that enables 

devices to learn of the existence of potential peer devices and the required 
information (an IP address) needed to establish TCP/IP connections to 
them. The successful result of an SSDP search is a Uniform Resource 
Locator (URL). The Hostname embedded in the URL can be resolved to an 
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IP address that can be used to make a connection to the discovered device. 

The name to address resolution is outside of the functionality of SSDP. 

SSDP specifies a default, completely automatic, best-effort multicast 

UDP-based operating mode, in addition to a server mode that uses TCP for 
5 registration and query. Fall-forward to server mode and fallback to the 

default dynamic mode can occur automatically and transparently as a 

server is added or removed from a network. Server mode can be used to 

reduce network traffic, to implement searches based on location or policy 

and to integrate with a directory system. 
10 SSDP requires that all devices specify a maximum lifetime that SSDP 

level knowledge of the device will remain cached in other network devices 

If a device does not refresh the cache of other network devices before this 

interval expires, the device will be assumed to have disappeared from the 

network. This interval can be chosen to be larger than a typical power 
1 5 down cycle to enable device visibility to persist for a relatively long time, or 

a smaller interval can be chosen to enable more dynamic visibility control. 

In all cases, devices that are abruptly removed from the network will 

eventually disappear from all networked devices. 

In response to an SSDP search, UPnP devices return a Description 
20 URL in the SSDP Location and optionally the Alternate Location (AL) SSDP 

headers. An example location header is a follows: 

Location: http://device.local/description/path/description.xml 

In this example, the device. local is the Hostname of the Controlled 

Device, and the "description/path/description.xml" element of the URL is 
25 the path and name of the Description Document on the device. 
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Eventing: Generic Eventing Notification (GENA) 

Eventing, in the context of UPnP, is the ability for a device to initiate 
a connection at any time to one or more devices that have expressed a 
desire to receive events from the source device. Events are used to enable 
5 synchronization among multiple devices organized into a many to one 

relationship. UPnP events are mainly used for asynchronous notifications 
of state changes. 

TCP/IP provides the fundamental support for the connections that 
carry event information reliably. Generic Event Notification (GENA) adds 
10 conventions for establishing relationships between interested devices and 
an addressing scheme to enable the unambiguous delivery of events. 
GENA leverages HTTP addressing and encapsulation. 

User Control Points, Controlled Devices, Bridges and OS Service 
Remoter/Publisher 

15 With reference now to Figures 1 and 2, UPnP is an application-level 

distributed network architecture where the logical nodes on the network 
are User Control Points 104-105, Controlled Devices 106-107, Bridges 
1 20, and OS Service Remoter/Publisher 1 50. These classifications refer to 
functionality rather than physical entities. The functionality of UPnP User 

20 Control Points 104-105, Controlled Devices 106-107 and Bridges 120 can 
be packaged into physical entities (e.g., multiple function devices 102-103) 
in any combination. 

The primary distinction between a User Control Point 104-105 and a 
Controlled Device 106-107 is that the User Control Point is always the 
25 communication initiator. After the initial communication, User Control 
Points can receive events from Controlled Devices. 
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Controlled Devices 106-107 are responsible for storing and updating 
the state of Services. User Control Points are required to synchronize to 
the state on Controlled Devices and to share state directly among 
themselves. 

5 User Control Points typically have user interface that is used to 

access one or more Controlled Devices on the network. Controlled Devices 
typically only have local user interfaces. 

Bridges 1 20 (Figure 2) expose devices that do not expose native 
UPnP protocols as native UPnP Controlled Devices. The Bridge itself looks 

10 to other UPnP User Control Points like a set of Controlled Devices. 

Service Remoter/Publisher 150 (Figure 2) exposes services 156-157 
of a general purpose operating system 152 (e.g., services provided in the 
Microsoft Windows operating system), hereafter referred to as OS services. 
The Service Remoter/Publisher 1 50 emulates a set of Controlled Devices 

1 5 providing the operational functionality of the OS services, and thus appears 
as a set of such Controlled Devices to the UPnP User Control Points 104- 
105. The Service Remoter/Publisher 150 then interacts with the OS 
services through the conventional OS API exposed by the OS services in 
response to the UPnP User Control Points 104-105 to effect remote control 

20 of the OS services from the UPnP User Control Points via the UPnP 
protocol. 

UPnP Publishing Service and Service Remoter 

With reference to Figure 3, the Service Remoter/Publisher 1 50 

(Figure 2) is implemented in an exemplary general purpose operating 

25 system 1 52, which may be for example the Microsoft Windows operating 

system, as a UPnP Publishing Service 160 and a Service Remoter 162. 
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The general purpose operating system 1 52 provides a variety of OS 
services 1 56 that perform specific system functions to support other 
programs, including application programs run on the operating system. The 
illustrated OS services 1 56 include date and time clock, file and printer 
5 sharing, print spooling, electronic mail, fax, telephony, file synchronization 
(e.g., with mobile devices), file backup and archiving, audio and video file 
streaming (e.g., from local or remote storage, and to a peripheral play-back 
device, such as speakers or a monitor), audio and video codecs, file 
compression/decompression, problem diagnosis and support, event logging, 

1 0 user and software configuration administration, security and access 

control, remote access (RAS), networking (Internet socket, FTP, HTTP, 
TCP/IP, NetBIOS, etc.), name and address (DHCP, DNS), remote procedure 
call (RPC) and named pipe, dynamic peripheral configuration (Plug and 
Play), and application scheduling <e.g., Windows 95 system agent), among 

15 others. In addition, the OS services can include extended services that 

plug into an extendible services architecture of the operating system, such 
as using the Microsoft Windows NT Services programming model (see, for 
example, J. Richter, Design A Windows NT Service To Exploit Special 
Operating System Facilities , Microsoft Systems Journal -(October 1997). 

20 The OS services 156 are exposed to programmatic control by applications 
and other programs running on the operating system through a set of OS 
APIs 166 (e.g., the Microsoft Win32 API, which is described in Microsoft 
Win32 Programmer's Reference , Microsoft Press (1993).) 

The UPnP Publishing Service 1 60 in the illustrated general purpose 

25 operating system 152 is a program structured as a service of that operating 
system (e.g., as a Windows NT Service), and provides a publishing API 
164. The UPnP Publishing Service 160 operates as a general mechanism 

* 
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for publishing the information necessary to emulate the functionality of 
devices and services running under the general purpose operating system 
as Controlled Devices per the UPnP protocol for devices and services that 
do not themselves support the UPnP protocol. The Service Remoter 162, 
5 the Bridge 120, as well as Applications 170-171 use the publishing API 
1 64 to establish a Controlled Device emulation of their functionality by the 
UPnP Publishing Service 160, and provide the communications (such as of 
the service state and Commands from User Control Points) between the 
programs and the UPnP Publishing Service to effect the emulation as 

10 Controlled Devices. The UPnP Publishing Service 160 operates to publish 
information such as discovery responses, service description, and service 
state, as well as direct responses to UPnP requests, to User Control Points 
104 for the set of Controlled Devices that it emulates. The UPnP 
Publishing Service 1 60 also passes information back to the devices and 

1 5 services running under the general purpose operating system (e.g., via a 

callback registered with the UPnP Publishing Service through the publishing 
API) to effect the Commands from the User Control Point 104 to the 
emulated Controlled Devices. Thus, for purposes of the User Control 
Points interacting with the emulated Controlled Devices in accordance with 

20 the UPnP protocol, the UPnP Publishing Service appears as the set of 
emulated Controlled Devices. 

The UPnP Publishing Service and publishing API allows the Service 
Remoter 162, the Bridge 120 and applications 170-171 to expose their 
functionality for remote control though the UPnP protocol without having 

25 to individually implement all the various components (described below and 
illustrated in Figure 5) of a Controlled Device per the UPnP protocol. 
Instead, the UPnP Publishing Service implements the components of a 
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Controlled Device collectively for the set of emulated Controlled Devices. 
The Service Remoter 162, the Bridge 120 and applications 170-171 need 
only be programmed to use the publishing API. 

The Service Remoter 1 62 is a program module that operates to 
5 convert between the specific OS API of the particular OS services, and the 
publishing API of the UPnP Publishing Service 160. The Service Remoter 
1 62 uses the publishing API to effect emulation of the particular OS 
Services as UPnP Controlled Devices by the UPnP Publishing Service 160, 
which exposes the OS services' operational functionality to remote control 

10 by User Control Points via the UPnP protocol. Also, as information is 

passed back from the UPnP Publishing Service 160, such as for Commands 
from the User Control Points in the UPnP protocol intended to control the 
OS services' operation, the Service Remoter 162 uses the regular OS API 
of the OS services to effect control of the OS services. This avoids having 

15 to restructure or reprogram the OS services as UPnP Controlled Devices, or 
even to themselves use the publishing API of the UPnP Publishing "Service 
160. 

Figure 4 illustrates an exemplary implementation of the UPnP 
Publisher/Remoter 1 50 (Figure 2) in the Microsoft Windows operating 

20 system. In this exemplary implementation, the UPnP Publishing Service 
160 includes an instance of the Service Remoter 162 per each OS service 
1 56 that is to be exposed as a UPnP Controlled Device, and a single SSDP 
Service 1 86 shared by all remoted operating system services 1 56 on the 
system. The Service Remoter 1 62 in this exemplary implementation fully 

25 implements a UPnP controlled device that remotely exposes the 

functionality of the respective OS service 156. The Service Remoter 162 
includes a set of library modules 190-198 that implement the various 
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discovery, description, eventing and control protocols of UPnP, as well as 
mapping code for converting communications with UPnP user control 
points per the UPnP protocol into interactions via the OS API with the OS 
service 156. These protocol modules includes a UPnP Publishing API 
5 library 190, a SSDP server library 191, an HTTP server library 192, a 

Sockets library 193, a GENA server library 194, a SOAP server library 195, 
a GENA publisher library 196, an HTTP client library 198, and an XML 
client library 1 97. 

The SSDP service 1 86 provides support for the SSDP discovery 

10 protocol for each OS service remoted through the UPnP Publishing Service 
160. The SSDP service 186 includes a separate instance of the Sockets 
library module 189 and a publish list 188. Each OS service 156 to be 
remoted through the UPnP Publishing Service 1 60 is added to the publish 
list 1 88 of the SSDP service 1 86 via a call to the UPnP Publishing API 

15 library 190 and SSDP server library 191. The SSDP Service 186 then 

provides appropriate responses to SSDP discovery requests per the UPnP 
protocol for the remoted OS service 1 56. 

The Service Remoter 162 handles incoming UPnP description 
requests and responses for the remoted OS service 1 56 via the Sockets 

20 library 1 93, the HTTP server library 1 92, and the UPnP Publishing API 
library 190 modules. 

The Service Remoter 162 handles incoming event subscribe requests 
for the remoted OS service 156 via the Sockets library 193, the HTTP 
server library 192, and the UPnP Publishing API library 190 modules. Data 

25 for out-going event publishing for the remoted OS service 1 56 (e.g., the 
service's state) is handled in the Service Remoter 1 62 through the UPnP 
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Publishing API library 190, the GEN A publish library 196, the HTTP client 
library 1 98 and the Sockets library 1 93 modules. 

The Service Remoter 1 62 further handles control commands of UPnP 
User Control Points to the remoted OS service 1 56 via the^-Sockets library 
5 193, the HTTP library 192, the SOAP server library 195, and the UPnP 
Publishing API library 1 90 modules. 

With reference now to Figure 5, the following table lists the modules 
in the User Control Points 104-1O5 and Controlled Devices 106-107, along 
with their functions. 

* * 

10 







Function Module 


Function Module 


Initiate discovery Discovery Client 

of Controlled 

Devices. 


Respond to Discovery 
discovery Server 
requests. 


Retrieve Description Client 

Description 

Documents. 


Provide Description 
Description Server 
Documents. 


Display a folder Visual Navigation 

of icons per 

discovered 

Device and allow 

transfer of 

control to a 

selected device. 
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View user Web Browser 
interface exposed 
by a Controlled 
Device. 


Provide user Presentation 
inteface for (Web) Server 
remote User 
Control Points. 


Execute Application 
applications. Execution 

Environment 




Invoke Rehydrator 

Commands on a 

Controlled Device 

by sending 

Service Control 

Protocols in 

rocrtnnco +/*\ \f\r*c»l 
1 co|JUilbc VvJ lUCal 

API calls. 


Accept) incoming Control Server 
Commands in plus native 
SCPs and control logic 
execute them. 

- 


Inform a Event 
Controlled Device Subscription 
of a desire to Client 
receive Events. 


Accept requests Event 

for Events and Subscription 

remember them. Server 


Receive an Event. Event Sink 


Send an Event. Event Source 


Device Model 

The UPnP Device Model 200 shown in figure 5 is the model of a 
UPnP Controlled Device or Bridge that is emulating native Controlled 



5 Devices. The Device Model includes the addressing scheme, eventing 

35 



WO 02/01833 PCT/US00/17844 



scheme, Description Document schema, Devices and Services schema and 
hierarchy, and the functional description of modules. The UPnP Device 
Model extends beyond simple API or a command and control protocol 
definitions to enable multiple User Control Points to have a consistent view 
5 of Controlled Devices. This requires that the state of running services be 
formally modeled and that all state changes be visible to User Control 
Points. Central to the distributed UPnP architecture is the rule that 
Controlled Devices are the ultimate authority for the state of Services 
running on them. 

10 UPnP Service 

The fundamental controllable entity in UPnP is a UPnP Service 210- 

217. Every running instance of a UPnP Service includes: 

• A Service State Table (SST) 230, which represents the current state of 

the UPnP Service. 

1 5 The SST 230 can be used to represent the operational mode of 

device or to act as an information source or sink for structured data or 
simple files. The SST of a VCR 254 (Figure 6) could represent the 
current transport mode, tuner channel selection, input and output 
switch selections, audio and video decoding format and current timer 

20 program. The SST of clock 251 (Figure 6) would likely represent the 

current time. The SST of an image rendering device could implement a 
video frame-buffer that can accept raw pixel information or formatted 
JPG files. The SST of an audio or video playback device could 
implement a transfer buffer or queue of material to be played. The SST 

25 of PDA could implement a collection of formatted data that has changed 
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and needed to be synchronized with another device, in addition to a 
transfer buffer for accepting incoming formatted data. 

The logical structure of a SST published in the Service Definition, 
but the actual storage format of an instance of a SST is entirely up the 
5 device. The only interaction with a SST is through a formal application 

level network protocol. 

• A Control Server 232, which accepts incoming Commands expressed in 

the UPnP Service's Service Control Protocol (SCP). The Control Server 

■ •. l 

passes the command to the UPnP Service's native command processing 
10 logic and waits for command completion. When the command is 

completed successfully, the SST is updated, an event is generated, and 
a successful response is returned to the User Control Point. In the 
event of an illegal command or unsuccessful command, no changes are 
made to the SST and a failure response is returned. The Command and 
15 response sequence is payload to a TCP/HTTP request/response. 

• An Event Subscription Server and Event Source 234. The Event 
Subscription Server accepts incoming GENA SUBSCRIBE messages from 
User Control Points and adds them to a list of User Control Points 
interested in SST change events from the UPnP Service. The Event 

20 Source initiates a TCP/HTTP connection to each interested User Control 

Point and sends a GENA NOTIFY each time the UPnP Service's DST 
changes. The NOTIFY payload includes the changed contents of the 
DST. 

• A Control URL that identifies the Control Server. 

25 • An Event URL that identifies the Event Subscription Server. 

The formal definition of a UPnP Service (Service Definition) includes: 
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• The definition of the SST. SST layouts are logically specified in terms 
of rows of [ Variable, Type, Legal Values, Default Value ]. The actual 
instance of a SST would also include a Current Value field in every row. 

• The definition of the Service Command Set that can be invoked against 
5 the UPnP Service's SST. Commands are logically specified in terms of 

Command ( Variable = New Value, Variable = New Value, ... ). If a 
Command results in more than a single Variable change, the updates, are 
atomic and the Command will fail if it is illegal to make the specified 
change to any one Variable. 

10 • The definition of a structured unit of data called a Service Control 
Protocol Declaration (SCPD). SCPD is used to advertise the layout 
(schema) of the SST and Command Set of the UPnP Service to a User 
Control Point or Bridge. The SCPD enables the User Control Point to 
invoke Commands (through the Rehydrator) on the Controlled Device 

1 5 without any prior or persistent knowledge of the capabilities of the 

device. The SCPD is uploaded from the Controlling Device as part of 
the Description Document. Generation of the SCPD for a UPnP Service 
based on its SST definition and Command Set definition can be fully 
automated. 

20 • The definition of a network protocol used to invoke Commands against 
the SST associated with a UPnP Service and to return results. The SCP 
can be generated from the SCPD. The Rehydrator's job is to convert 
SCPDs into SCPs. The reason for a formal SCP specification is to 

* 

enable the implementation of the Control Server itself and to enable 
25 simple peer-to-peer device interoperation using only published protocols. 
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• An identifier, called the Service Type Identifier, that identifies a unique 
Service Definition. Service Definitions are versioned in controlled 
manner. Every later version of a UPnP Service must be proper superset 
of the previous version. 

5 Device 

According to the device model 200 shown in Figure 5, a UPnP 

Device 202-205 (e.g., multiple function devices 102-103 of Figure 1 and 

bridged devices 122-123 of Figure 2) is a logical container of one or more 

UPnP Services 210-217. Generally a Device represents a physical entity 

10 such as a VCR. Typical UPnP Services in the VCR Device example might be 
'TRANSPORT", "TUNER", "TIMER" and "CLOCK". While Devices are 
often physical entities, a PC emulating the traditional functions of a VCR 
could also be modeled in the same way as the stand-alone VCR. Devices 
can contain other Devices. An example would be a TV/VCR 250 -(Figure 6) 

1 5 packaged into a single physical unit. A Device (e.g., devices 202-203) 

may also be a logical container of other Devices. The top-most Device in a 
hierarchy of nested Devices 203-205 is called the Root Device 202. A 
Device with no nested Devices is always a Root Device. 

The UPnP Device Model was designed to be general and flexible. It 

20 should be possible to rriodel an entire Nuclear Power Plant as a single UPnP 
Service or as a deeply nested hierarchy of Devices and UPnP Services. In 
general, a UPnP Service 210-217 is cohesive -set of functions that enables 
flexible packaging into a variety of Devices. UPnP Services can be 
versioned independently of Devices. 

25 All Devices, including Root Devices belong to one or more Device 

Types. Device Types are intended to enable instances of Devices to toe 
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simply and automatically grouped for presentation. An example of a 
Device Type is "VCR" 254 (Figure 6). Device Types are formally defined in 
terms of a minimal set of versioned UPnP Services that a Device of Device 
Type must support. Device Types are not formally versioned. Device Type 
5 is a relatively high level grouping. A Device of Device Type only ensures 
that minimal set of UPnP Services of a minimal version is present. There 
can be other UPnP Services, higher versioned UPnP Services and UPnP 
Services with vendor extensions present on such a Device. 

UPnP enables SSDP level searches for a unique instance of a Device 

10 (by UDN), all Devices of type Device Type and all Devices that contain at 
least one Service Type of minimum version. The result of an SSDP search 
is always a URL that points to the Description Document contained in the 
Root Device. In the event that matching Device is not the Root Device, the 
Description Document has a tree of nested Devices that can be traversed 

15 to find the matching Device. 

Every Device includes: 

• One or more Device Types. 

• One or more UPnP Services. 

• Optionally, one or more Devices. 

20 • Optionally, a Presentation (Web) Server 220-223 that can be used to 
expose Device user interface. Every Presentation Server has an 
associated Presentation URL. 

• A globally unique identifier called the Unique Device Name (UDN). The 
UDN is the fundamental identifier of an instance of a Device. Every 

25 Device, including Root Devices, has exactly one UDN. 
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Every Root Device 202 also includes the Description Document 226 
and Description Server 228 for all Devices under and including itself. 

The formal definition of a Device (Device Definition 226) includes: 

• The fixed elements of the Description Document that describe the 
5 Device. 

• The required hierarchy of Devices and Service Definitions. 

There can be many Device Definitions that belong to a single Device 

Type. 

i • 

Device Types 

10 The formal definition of a Device Type includes: 

• A Device Type Identifier. 

• The required hierarchy of Devices and Service Definitions of minimum 
versions. 

Service State Table 
15 A Service State Table (SST) logically consists of rows of: 

Variable, Type, Legal Values, Default Value, Current Value 

Although entries of the Service State Table in UPnP consist of these five 

items, the state table alternatively can contain fewer or additional items. 

Generally, each entry will minimally consist of a Variable name or identifier, 

■ *■ * 

20 and its current value. 
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The following table lists various Types available in UPnP. 



u Type f y . a., v 


■ j .Description;- ■>;>• v-* •* > w> v ^ $ i; * *, 


■-•■■> -* - j - i' .. j - 1 


otring 


A sequence of UNICODE characters. 


• 


Number 


A number/ with no limit on digits; may 


15, 3.14, - 




potentially have a leading sign. 


123.456E+10 




fractional digits, and optionally an 






• 

exponent. Punctuation as in US 










Boolean 


TRUE or FALSE. 




DateTime 


A date in IS08601 format, with 


19941105X08:1 




optional time and optional zone. 


5:5 + 03 




Fractional seconds may be as precise 






as nanoseconds. See, Data Elements 






And Interchange Formats - Information 






Interchange - Representation Of Dates 






And Times, International Standard. ISO 






8601, First Edition 1988-06-15. 




ByteBlock 


An unstructured sequence of bytes. 





5 The ByteBlock is essentially a data buffer. In one use, a variable of 

this type can be used to effect transfer of a file from the Controlled Device 

« 

to the User Control Point. The file to be transferred is kept in the Service 
State Table as the current value of this variable. On a change in the file, 
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the file is transferred to any subscribing User Control Point in an event 
notification. 

The reason for representing UPnP Services this way is to ensure that 
the state of a UPnP Service is easily available in a common way to multiple 
5 User Control Points. 

An SST can be used to represent to current operational mode of 
device, act as an information source or sink and/or simply be a repository 
for commands. The SST of a VCR UPnP Service could represent the 
current transport mode, tuner channel selection, input and output switch 
10 selections, audio and video decoding format and current timer program. 
Alternatively, the VCR 254 could be represented as a Transport UPnP 
Service 260, Tuner UPnP Service, I/O Switch UPnP Service, A/V Decoding 
Configuration UPnP Service and Programmable Timer UPnP Service 261 . 
The SST of a clock 251 would likely represent the current time. 
1 5 Additionally an alarm clock could include Service Variables to configure the 
clock. 

The SST of an image rendering device could implement a video 
frame-buffer that can accept raw pixel information or formatted JPG files. 
The SST of an audio or video playback device could implement a transfer 
20 buffer of queue of material to be played. The SST of PDA could implement 
a collection of formatted data that has changed and needed to be 
synchronized with another device, in addition to a transfer buffer for 
accepting incoming formatted data. 

User Control Point Synchronization 
25 In accordance with an device state and eventing model illustrated in 

Figure 7, UPnP rules require that every change to an SST generate a 
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corresponding event to announce the change to the all interested User 
Control Points. 

Device Addressing 

With reference now to Figure 8, UPnP is built on top of HTTP and 
5 leverages the native address format of the Web, Uniform Resource 
Locators (URLs), URLs minimally contain an identification of the 
application protocol family ("http") that the URL is valid for, a Hostname 
and a path. In the context of UPnP, the path part of a URL can represent 
either a filesystem path or simply an identifier of the local system module 

10 and context that can process incoming messages. 

While UPnP modules are described as HTTP servers, there is no 
requirement that implementations be based on actual Web servers. In most 
cases, the job of the HTTP server is simply to accept the incoming 
connection, look at the local destination part of the address (the path) and 

1 5 forward the payload to another module. UPnP enables, but does not 
require, that all HTTP Servers be based on a common software 
implementation or runtime instance. Controlled Devices and Bridges can 
include a TCP port specification as part of a URL to override the default 
value of 80. 

20 The successful result of a SSDP level search in UPnP is always one 

or more Description URLs. These URLs can be used to navigate to the 
Description Document of a Controlled Device or Bridge. A User Control 
Point uploads the Description Document and extracts the URLs of the 
Servers running on the Controlled Device or Bridge. 

25 All URLs returned in the Description Document have a lifetime equal 

to the lifetime of the Hostname embedded in them. User Control Points 
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can store these URLs as addresses without going through a search 
sequence first. Once they have been advertised in a Description 
Document, Controlled Device and Bridges cannot arbitrarily change Server 
URLs. 

5 Whenever a Hostname changes, all URLs associated with all Devices 

addressed by that Hostname are invalidated. The UON is the only UPnP 
identifier guaranteed never to change. Any persistent associations 

maintained by applications should at least store the UDN to able to 

• ■ -i 
unambiguously identify the target Device. 

10 The lifetime of a Description URL is determined by Controlled Device 

or Bridge that advertises it. If a Controlled Device or Bridge allows an 
SSDP advertisement of a Description URL to expire, the URL is invalidated. 

User Control Points use the Event Subscription URL returned by the 
Controlled Device or Bridge to connect to the Event Subscription Server. 

15 This server does the housekeeping of remembering all User Control Points 
that are interested in receiving Events on a UPnP Service. The Event 
Subscription Server needs an address to send the events back to. This 
address is called the Event Sink URL, and is supplied to the Controlled 
Device or Bridge in the GENA SUBSCRIBE message. The lifetime of an 

20 event subscription, and the Event Sink URL, is determined by the timeout 
on the SUBSCRIBE message. 

Further details of UPnP addressing are listed in the following table. 
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UPnP Addresses 


URL 1 ;v 


Function-;;- ^^iy'iH^l ! ^MH^-^^i^ 


Description 
URL 


Points to the Description Server and Document path on a 
Root Device. This URL is returned by the Description 
Server as part of the discovery process. 


Presentation 
URL 

• 


Points to a Presentation (Web) Server on a Controlled 
Device. There is one Presentation URL per Device, 
including Root Devices. This URL can be entered into the 
address bar of a Web browser to navigate to the root 
Web page of a Device. This URL is returned in the 
uescripxion uocument. 


Control URL 


Points to the Control Server implementing a UPnP Service 
on a Controlled Device. There is one Control URL per 
instance of a UPnP Service Thi«; LJRI i«? rf>tiirn*»H in th<=» 

Description Document. 


Event 

Subscription 
URL 

• 


Points to an Event Subscription Server on a Controlled 
Device. This URL is returned in the Description Document. 


Event Sink URL 


Points to an Event Sink (an HTTP Server) on a User 
Control Point: This URL is specified by the User Control 
Point in the GENA SU8SCIBE message. 
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Device Discovery and Identification 

UPnP enables SSDP searches for a unique Root or non-Root Device 
by UDN, devices of a specified Device Type and devices containing a UPnP 
Service of a specified Service Type. 

5 



UPnP SSDP Level Searches and Results 


Search for u *S<:, 


■/■ Returns' % *■ y V> * : % **= £ ^ A-:*.'*: * * a 1 


A unique Root 
Device (by 
UDN) 


A single Description URL pointing to the Description 
Server and Document path on the Root Device. 


A unique non- 
Root Device (by 
UDN) 


A single Description URL pointing to the Description 
Server and Document path on the Root Device that 
contains the non-Root Device!. 


Type of Device 


A set of Description URLs pointing to the Description 
Servers/Document paths of all Root Devices that match 
the Device Type, or contain a non-Root Device that 
matches the Device Type. 


Type of Service 


A set of Description URLs pointing to the Description 
Servers/Document paths of all Root Devices that contain 
a matching UPnP Service, or contain a non-Root Device 
that contains a matching UPnP Service. 



SSDP specifies Service Type (ST), Notification type (NT), and Unique 
Service Name (USN) header fields for queries and for announcements. 
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UPnP uses the ST or NT header to carry one of the UPnP defined 
identifiers. A unique USN is required for each unique SSDP announcement. 

Multiple instances of the same Service Type within a Controlled 
Device 106-107 or Bridge 120 are not independently announced. 
5 UPnP search identifiers are used during the discovery process. The 

result of a successful discovery is one or more Description URLs. The 
format for search identifiers is: ' 

upnp: search type: [ allformat \ UDNformat | 
10 srv format \ dev format ] 

searchtype = [ UDN | SrvType | DevType I all 

] .. 

15 allformat = all 

UDNformat « namespace: unique id 

namespace = [ GUID | IEEEMAC | 1394] 

20 srvformat = SrvType: servicetype: version 

dev format - DevType ; device type 



UPnP Search Identifiers 





W, , Formats <- : f K \. f -K ••;"'«: 




all 


upnp:all 


upnp:all 


Unique Device 


upnp:UDN:namaspace:t/ 


upnp:UDN:IEEEMAC:0CO09 


Name (UDN) 


niqueid 


9123456 


Device Type 


upnp:DevType:ctev/cefy 
pe 


upnp:DevType:vcr 


Service Type 


up n p : S rvTy pe iservicety 


upnp:SrvType:clock: 1 
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peiver 



SSDP specifies that SSDP announcements must be made for all 
SSDP searchable values. The SSDP announcements with "all" as the 
notification header value must carry the Root Device UDN as the USN 
5 header value. SSDP announcements for Device Types must carry the UDN 
of the Root Device concatenated with the Device Type URI as the USN 
header value. SSDP announcements for a Service Type will carry the UDN 
of the Root Device concatenated with the Service Type URI value as the 
USN header value. SSDP announcements of UDNs will repeat the UDN 
10 value as the USN header. 



UPnP SSDP Announcements 



\. Announcement <X 

L- A' -f'> ■? ?i :■ . V r - r,,. '. 


; UPnP Notification 


¥ SSDP il.SN: V-"* \'i '< ft "- W 

r^K. »... s .t s fcj, £ ».A * 

sr. *«. .! : M -".-js .,4- / . .r- . "* S--. » ^ | 




"all" 


Root Device UDN 


Unique Root 
Device 


Root Device UDN 


Root Device UDN 


Unique non-Root 
Device 


Non-Root Device 
UDN 


Non-Root Device UDN 


Device Type 


Device Type 
Identifier 


Root Device UDN + Device Type 
Identifier 


Service Type 


Service Type 
Identifier 


Root Device UDN + Service Type 
Identifier 
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UPnP Bridges 120 (Figure 2) announce Bridged Devices 122-123 and 
associated UPnP Services using SSDP. The identifiers associated with the 

* 

Bridged Devices are unique for the device, and they do not duplicate 
identifiers for Controlied Devices and UPnP Services directly available on 
5 the Bridge itself. This means that a Bridge that is also a Controlled Device 
must announce Bridged Devices and local Controlled Devices 
independently, with appropriate unique identifiers, Description Documents 
and associated URLs. 

# ■ 

Description 

10 The UPnP Description Document 226 (Figure 5) provides the 

information necessary to identify, describe, connect and control a UPnP 
Controlled Device 106-107 or Bridge 120 from a User Control Point 104- 
105. 

The Description Document is an XML document. UPnP defines the 
1 5 use of HTTP and XML for the Description Document and wire protocols. 
UPnP adheres to the schema declaration rules of XML-Data and Y. Goland, 
"Flexible XML Processing Profile." - 

The top level XML elements are separated into three categories: per 
Device, per UPnP Service and shared. 

20 Rehydrator 

With reference now to Figure 9, all (UPnP) Controlled Devices 106- 

107 (Figure 1) or Bridges 120 (Figure 2) expose one or more UPnP Services 

210-217 (Figure 5) that can be controlled remotely. Controlling such UPnP 

Services involves a message exchange between a User Control Point 1*04 

25 and the device 106. This message exchange happens according to a 
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specific Service Control Protocol (SCP) 402, which specifies the content 
and sequence of the messages exchanged. 

User Control Points 104 are not required to have any prior 
knowledge of the SCPs 402 required to control the UPnP Services on the 
5 various devices. Therefore, a Controlled Device or Bridge must he able to 
describe to a User Control Point the protocols required to control its UPnP 
Services, such that the User Control Point will be able to implement these 
protocols dynamically. This requires a standard way of declaring Service 
Control Protocols in a concise and unambiguous fashion. UPnP introduces 
10 a technique for declaring Service Control Protocols using a series of XML 
documents. 

A Rehydrator 410 is a module that exposes a suitable API to 
applications and either invokes Commands on a UPnP Service or queries 
the state of that UPnP Service, or receives and responds to events. The 

1 5 primary job of the Rehydrator is to map between API calls and the Service 
Control Protocol sequence that invokes the Command. 

As part of the Service Definition 406, a Service State Table 230 and 
Command Set 408 are defined. These things can be combined in a 
deterministic way defined by UPnP to produce a Service Control Protocol 

20 Definition (SCPD) 406, which includes a Service Control Declaration 404 
and a Service Control Protocol 402. The SCPD 406 is a representation of 
the schema of a UPnP Service. It is possible to reconstruct the SST, 
Command Set and SCP from the SCPD. 

The SCPD is directly embedded into the Description Document 226 

25 of a Controlled Device. When the Description Document is uploaded into 
the User Control Point 104, the Rehydrator 410 can extract the SCPD from 
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it. At this point, the Rehydrator has enough information to issue UPnP 
Service specific SCPs 402. 

General Operation of the Rehydrator 

More generally with reference to Figure 10, the Rehydrator 410 
5 operates as a universal adapter to provide a programmatic interface to any 
service-specific protocol of a remote computing device. The Rehydrator 
410 simply obtains a data description or declaration of the methods, 
properties and events of the remote UPnP Service, as well as a definition of 

■ 

the protocol of network data messages through which the Rehydrator 

10 invokes the methods, queries or sets the properties, and receives event 
notifications. In UPnP, this data description takes the form of the 
Description Document 226, which contains a Contract 412. The Contract 
defines network data packets 413 fe.g., XML data), request/response 
patterns, and protocol (e.g., GENA, HTTP, SSDP) via which the packets are 

1 5 exchanged. This information is sufficient for the Rehydrator to exchange 
the appropriate network data packets to interact with the Controlled Device 
Service, including to invoke commands, query and set properties, and 
receive and respond to events, without download of any executable code 
to the User Control Point 1 04 device and with a zero installation or 

20 configuration experience. 

The Description Document 226 also includes a declaration of the 
methods, properties and events for the UPnP Service. Based on this 
declaration, the Rehydrator produces a corresponding programmatic 
interface for use by applications at the User Control Point. The 

25 programmatic interface is an application programming interface that can be 
in the form of an object integration interface of an object-oriented 
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programming model, such as Microsoft COM, CORBA, Java classes, and 
scripting engine name extensions. In the example illustrated in Figure 10, 
the Rehydrator 410 exposes a COM object integration interface riClock" 
interface 414), with methods getTimeO and setTime(), for a Controlled 
5 Device having a "Clock" UPnP Service with GetTime and SetTime 

* 

commands. The Rehydrator 410 converts calls of an application program 
416 to the ICIock interface 414 into the network data messages specified 
in the Contract to invoke the corresponding commands of the Clock -UPnP 
Service. The Rehydrator 410 likewise creates suitable further 

10 programmatic interfaces for other UPnP Services (e.g., UPnP Services 210- 
217 of Figure 5) based on the Description Document of their respective 
Controlled Devices. 

Accordingly, the Rehydrator operates as a universal proxy object 
with data-driven conversion of programmatic interfaces to network data 

15 messages. Further, the Rehydrator produces the programmatic interface at 
the User Control Point based solely on an XML data description. This 
operation allows the Rehydrator to produce just-in-time transient interfaces 
to remote device UPnP Services without the complexity of code downloads 
and installation or configuration. Upon a later release of the interface by 

20 the application, the Rehydrator destroys the interface without need to de- 
install or clean up persistent configuration data in a registry or configuration 
file of the operating system or object execution run-time. 

Rehydrator Implementation 

Summary . With reference to Figure 1 1 , a preferred implementation 
25 440 of the Rehydrator 410 is as an internal Microsoft Windows component 
that routes service control requests from the UPnP API to devices. 
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Applications wishing to control a UPnP Service on a UPnP device obtain a 

Service object through the UPnP API and use the methods of this object to 

query the state variables of the UPnP Service and invoke its actions. Those 

methods use the Rehydrator API to turn the UPnP Service control requests 
5 into network messages that travel to the UPnP device. In this sense, the 

Rehydrator performs; a mapping between API calls and network protocols. 
Basic Functionality . The preferred implementation of the Rehydrator 

is able to translate a service control call to the UPnP API into the 

appropriate network messages defined by the Service Control Protocol. 
10 Asynchronous Event Notification . The preferred implementation of 

the Rehydrator is able to notify UPnP API clients of any asynchronous 

events generated by the devices they are controlling. Event notification is 

done by means of the event interfaces defined below. 

Error Reporting . For a variety of reasons, state variable queries and 
1 5 action invocations may fail. The preferred implementation of the 

Rehydrator is able to provide a way to communicate the success or failure 

status of such operations to the parties initiating them. 

Rehydrator Implementation Design . As illustrated in Figure 1 1 , the 

preferred implementation of the Rehydrator is used in two ways. First, the 
20 Device Finder 450 uses it to create Service objects 460. Then, these 

Service objects use it to carry out service control operations (querying state 

variables and invoking actions). 

Creating Service Objects . When the Device Finder 450 creates a 

Device object, it invokes the Rehydrator 410 to create Service objects 460 
25 for each of the service instances on that device. Each service instance 

supports a particular Service Control Protocol and the Rehydrator needs a 
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description of this protocol in order to create a properly hydrated -Service 
object. 

The Service Control Protocol is declared in two separate XML 
documents: the DCPD and the Contract. The Rehydrator needs the 
5 information in both documents. These two documents are passed to the 
Rehydrator as IXMLDOMDocument interface pointers in the 
RehydratorCreateServiceObjectO API call. 

HRESULT 

10 RehydratorCreateServiceObject ( 

IN IXMLDOMDocument *pDCPD, 

IN IXMLDOMDocument *pCont r act Document , 
GUT IUPnPService **pNewServiceObject) ; 

1 5 This API returns a pointer to an IUPnPService interface on a newly 

created Service object. In addition to the creating the Service object, the 
Rehydrator sets up its internal data structures so that it can properly handle 
requests to control the UPnP Service. Specifically, it creates a list of the 
properties and actions exported by the UPnP Service. Since all service 

20 instances of the same service type export the same properties and the 

same actions, this information is kept only once for each service type and 
is indexed by Service Type Identifier. 

The Rehydrator stores the information that is specific to a particular 
service instance as private data within the Service object itself. This 

25 includes the control URL and information about the control server 232 
(such as the HTTP verbs it supports). The Service Type Identifier is the 
link between the Service object that represents one instance of a service 
type and the Rehydrator internal data structures that contain information 
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common to all instances of that service type. The Service Type Identifier is 
stored as a private data member in the Service object. 

Querying Service Properties . Applications can query the values of 
service properties by invoking the IUPnPService::GetProperty() method on a 
5 Service object. Internally, this method makes a call to the 
RehydratorQueryStateVariableO function. 

HRESULT 

RehydratorQueryStateVariable ( 



IN 


LPCTSTR 


lpcszVerb, 


IN 


LPCTSTR 


lpcszControlURL, 


IN. 


LPCTSTR 


lpcszSTI, 


IN- 


LPCTSTR 


IpeszVarName, 


CUT 


VARIANT 


*pValue); 



15 

The first two in parameters to this function supply the service 
instance specific information: the HTTP verb to use and the control URL to 
which the network messages will be targeted. The third parameter is the 
Service Type Identifier that will be used to locate the Service Control 

20 Protocol information in the Rehydrator's internal data structures. The 
fourth parameter is the name of the variable that is being queried <the 
Rehydrator will validate this against is internal list of state variables 
exported by the UPnP Service) and the final parameter is the address of a 
. VARIANT structure in which the Rehydrator will place the variable's value. 

25 This function will generate an HTTP request to the control server on 

the device. The body of this request will be an XML fragment containing a 
XOAP-encoded request for the variable's value. The following is an 
example of such a request (the exact header and payload format of this 
message is defined in the service contract): 
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M-POST /clockService HTTP/1.1 
Host: spather-xeon: 858 6 
Content-Type: text/xml 
5 Man: 

"http: //www. microsoft . com/protocols /ext/XOAP" ; 
ns=01 

01-MethodName : queryStateVariable 
01-MessageType: Call 
10 Accept-Language: en-gb, en;q=0.8 

Ref erer : http : //myhouse/VCRl Presentation 
Content-Length: 8 4 

User-Agent: Mozilla/4.0 (compatible; MSIE 5.01; 
Windows NT 5> 0) 
15 Connection: Keep-Alive 

<queryStateVariable> 

<variableName>currentTime</variableName> 
</queryStateVariable> 



20 



The control server will respond to this message with another XML 
fragment: the XOAP-encoded method response. The following is an 
example of such a response: 



25 HTTP/1 . 1 200 OK 

Connection: Close 

Cache-Control: private 

-Date: Mon Oct 11 12:13:38 PDT 1999 

Expires: Mon Oct 11 12:13:38 PDT 1999 

30 Content-Type; text/xml 

Content-Length: 62 
Man : 

"http : //www. microsoft . com/protocols /ext/XOAP" ; 
ns=01 

35 01-MessageType: CallResponse 

<queryStateVariableResponse> 

<_return>12 : 13 : 28</_return> 
</queryStateVariableResponse> 
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The rehydrator will extract the return value from this XML fragment, 
place it in the VARIANT structure whose address was passed as the last 
parameter to RehydratorGetServicePropertyO and then return. 
5 Invoking UPnP Service Actions . The process of invoking a UPnP 

Service action is very similar to querying a state variable. An application 
calls JUPnPService:;lnvokeAction() on a Service object, passing it the name 
of an action to invoke, and an array of arguments to the action. Internally, 
lUPnPService::lnvokeAction() calls RehydratorlnvokeServiceActionO, 
10 declared as shown below. 

HRESULT 

RehydratorlnvokeServiceAction ( 

IN LPCTSTR lpcszVerb, 

15 IN LPCTSTR lpcszControlURL, 

IN LPCTSTR lpcszSTI, 

IN LPCTSTR lpcszActionName, 

IN SAFEARRAY saActionArgs , 

OUT LONG *pStatus); 

20 

As was the case for querying state variables, the service instance 
specific information is passed in the first two parameters, followed by the 
Service Type Identifier in the third. The action name and an array of 
arguments are passed as the next two parameters, and the final parameter 
25 is the address of a variable in which to store the status of the operation. 

RehydratorlnvokeServiceActionO will send an HTTP request to the 
control server identified by the second parameter. As before, the body of 
this message will be an XML fragment containing a XOAP-encoded method 
call. An example HTTP request to invoke an action is shown below. 

30 
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M-POST /clockService HTTP/1.1 
Host: spather-xeoh: 858 6 
Content-Type: text/xml 
Man: . 

5 "http : / /www .microsoft . com/protocols /ext/XOAP" ; 

ns=01 

01-MethodName : invokeAction 
01-MessageType: Call 
Accept-Language: en-gb, en;q=0.8 
10 Referer : http: //myhouse/VCRlPresentation 

Content-Length: 119 

User-Agent: Mozilla/4.0 (compatible; MSIE 5.01; 
Windows NT 5.0) 

Connection: Keep-Alive 1 



15 



<SerializedStream main="invokeAction"> 
<invokeAction id="invokeAction"> 



<actionName>setCurrentTime</actionName> 
20 <actionArg>15 : 41 : 29</actionArg> 

< / invokeAct ion> 
</SerializedStream> 

The encoding of the body of this message is again specified in the 
25 service contract. The Rehydrator will wait for the HTTP response to this 
request, which would look something like the example below. 

HTTP/1.1 200 OK 
Connection: Close 
Cache-Control: private 
30 Date: Mon Oct 11 15:22:38 .PDT 1999 

Expires: Mon Oct 11 15:22:38 PDT 1999 
Content-Type: text/xml 
Content-Length : 50 
Man: 

35 "http : //www. microsoft . com/protocols /ext/XOAP" ; 

ns=01 

01-MessageType: CallResponse 

<invokeActionRespbnse> 
40 <_return>0</_return> 

</invokeActionResponse> 
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After receiving a response such as this, the Rehydrator will extract 
the return value, place it in the out parameter it was passed, and then 
return. 

5 Figures 30 through 40 are program listings defining various 

interfaces used in the preferred implementation of the Rehydrator, including 
an lUPNPDevice Interface, an MJPNPPropertyBag Interface, an 
lUPNPService Interface, an lUPNPDevices Interface, and an lUPNPServices 
Interface. 

10 Description Document 

With reference to Figure 15, User Control Points 104 can retrieve a 

Description Document 226 by issuing an HTTP GET on a Description URL. 

This URL is returned in the location header of either an SSDP 

announcement or an SSDP query response. 

15 The HTTP<3ET must include an accept-language header that is used 

to request the preferred language of the response. If the requested 
language is not supported, a Description Document in the default language 
supported by the Controlled Device or Bridge may be returned. 

An HTTP GET is used to retrieve sub elements of a Description 

20 Document that are expressed as URLs. 

URL Handling 

URLs embedded in Description Documents 226 take one of 3 forms: 
a fully qualified URL or a relative URL. 

Fully qualified URLs take the form: 

25 http: //devicename/pathname 
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The devicename part of the URL is a Hostname or IP address and the 
pathname is a filesystem path or equivalent. A fully qualified URL is used 
"as is" to establish an HTTP connection to a device. 

A relative URL does not contain the character and is of the form: 

5 pathname 

/pathname 

Relative URLS are a compact representation of the location of a 
resource relative to an absolute base URL. All relative URLs in a Description 
Document are appended to the value of the Description Document element 
10 <URLbase> to form fully qualified URLs. 

Binary Data 

Some elements of a Description Document are binary. XML does not 
directly support the embedding of binary data. In order to include binary 
data directly in a Description Document, one must convert the data to text 

1 5 using the Base 64 encoding scheme. This tends to increase the size of the 
data by 25% on the average. Much of this overhead can be eliminated if 
the binary data is passed by reference instead of by value. To reference 
binary data, a URL to the data is provided in a Description Document. The 
binary data can be retrieved by doing a HTTP GET with that URL. 

20 As an example, consider the < image > element in the following 

Description Document: 

<iconList> 
<icon> 

25 <size>16</size> 

<imageType>PN<S</imageType> 
<color>l</color> 
<depth>8</depth> 
< image > 

30 " http : / /device . local /iconpath/icon . png" /> 

• 
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</icon> 
</iconList> 

The icon would be retrieved with an HTTP GET of the following 
5 format: 

GET iconpath/icon.png HTTP 1.1 
Host: device. local 

, * ♦ - 

1 0 The HTTP response would look like: 

HTTP/1.1 200 OK 
Content-Type: image/png 
Content-length: ### 
15 <binary color icon data in the PNG format> 

Description Document Layout 

The basic layout of the Description Document 226 is shown in 
Figure 16. 

The following table lists Description Document elements that are 
20 sub-elements to the root element. 



Root 

- 


The XML root element of a UPnP Description Document. 


specVersionM 


The major version of the UPnP Architectural Reference that 


ajor 


this Description Document was created against. This value 




must be 1. 


specVersionM 


The minor version of the UPnP Architectural Reference that 


ajor 


this Description Document was created against. This value 




must be 0. 


URLBase 


An optional element used to construct fully qualified URLs. 
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neiaxive unLo are appenaea to tne value ot <URLBase> to 

• 


- 


create fully qualified URLs. If this element is present, it must 




agree with the HTTP Base header. 


manufacturer 


A required element that contains a textual manufacturer 




name. 


manufacturer 


An optional element containing a URL that points to the Web page of 




the manufacturer. 


URL 


* 


modefName 


A required element containing a textual product name. 


modetDescrip 


A required element containing a textual product description. 


tion 


* t 

■ 


modelNumber 


An optional element containing a textual product model 




number. 

V 


modelURL 


An optional element containing a -URL that points to the Web 




page of the product. 

m * 


UPC 


An optional element containing the product Universal 




Product Code (UPC). 


serialNumber 


An optional element containing a textual item serial number. 


The Description Document elements listed in the following table are 


associated with devices. 


rootDevice 


A required sub element of the root. This element is a 




container for one or more service elements and the elements 




that describe the rootDevice. 
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device 


An optional sub element of the root or another device 


• • 


element. This, element contains the same kinds of elements 




as a rootOevice element. 


i irtM 
UDIM 


A required sub element of every rootDevice or device element 


• 


containing the Unique Device Name. 


friendlyName 


A required sub element of every rootDevice or device element 




containing a textual friendly name. This element can be 




updated remotely. 


deviceType 


A required sub element of every rootDevice or device element 




containing a standardized Device Type Identifier. 


presentation 


An optional sub element of a rootDevice or device element 


URL 


containing a Presentation URL. 


iconList 


A required sub element of every rootDevice or device 


* 


element. This element is a container for one or more icon 


- 


elements. UPnP requires a base set of six icons that must 


• 


exist in the iconList. All devices must support PNG icon 




image formats of three sizes, 1 6 by 1 6, 32 by 32 and 48 by 




48 pixels in both color and black and white at 8 bit depth. 




Additional formats and sizes, including JPEG, GIF, BMP, 




ICON and VML, may be supported by adding them to the list. 


icon 


A required sub element of every iconList element. This 




element is a container for the elements that define an icon. 


size 


A required sub element of every icon element. There must be 




icon elements with associated size elements with the values 
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16, 32 and 48. Other icons may specify other sizes. 


color 


A required sub element of every icon element with value O or 




i . bach icon of size 1 o, 32 or 48 must exist in color and 




black and white. 


depth 


A required sub element of every icon element. All required 




icons must exist with a value of 8. 


imageType 


A required sub element of every icon element that identifies 




the format of the binary icon: phg, jpeg, vml, gif, bmp, or ico. 


image 


A required sub element of every icon element that references 




a binary icon. 


The following elements of the Description Document are associated 


with UPnP Services. 


service 


An optional sub element of the rootDevice or another device 




element. This element is a container for the Service Definition. 


serviceTyp 


A required sub element of every service element containing a 


e 


standardized Service Type Identifier. 


controlUR 


A required sub element of every service containing a Control 


L 


URL. 


eventSubU 


A required sub element of every service containing an Event 


RL 


Subscription URL. 


SCPD 


A required sub element of every service. The SCPD is a 




container for the standardized Service Control Protocol 
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Declaration associated the Service. 



Figure 1 7 shows an exemplary icon list in a Description Document 

226. 

Service Control Protocol and SCP Declaration 
5 As part of the Service Definition 406 shown in Figure 9, a Service 

State Table 230 and Command Set 408 are defined. The SCPD 406 is a 
representation of the schema of a UPnP Service. It is possible to 
reconstruct the SST 230, Command Set 408 and SCP 402 from the SCPD 
deter ministically. 

1 0 The declaration of such a protocol must specify the list of Variables 

that can be queried, the set of Commands that can be invoked, as well as 
the wire protocol (the content and sequence of network messages) 
required to carry out these operations. SCPD is specified in two XML 
documents. The first or Service Control Definition document 404, written 

15 in a language called Service Control Protocol Declaration Language 

(SCPDL), declares the list of state Variables and Commands associated 
with the Service Type to be controlled by the protocol. The second or 
Service Control Protocol document 402 declares the wire protocol that will 
be used to query the values of the state variables and invoke the actions 

20 associated with the UPnP Service. 

Declaring the Service State Table and Command Set 

A SCPDL document 404 is used to specify the list of state Variables 

that a SCP can query and the set of Commands that it can invoke. SCPDL 

is an XML schema, a set of rules for writing XML documents (Service 

25 Control Protocol Declarations). 
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Figure 1 8 shows an exemplary SCPDL document. This XML 
document consists of a root <scpd> element containing two sub- 
elements, <serviceStateTab/e> and <actionList> . Within the 
<serviceStateTable> element is a <stateVariab/e> etement for each state 
5 variable associated with the UPnP Service. The UPnP Service in this 
example is a TV tuner with has only one state variable, currentChannel. 
The elements within the < state Variable> element specify the name, data 
type and allowed values for the state variable. Had the UPnP Service more 

■ 

state variables, they would be represented by additional <stateVariable> 
10 elements within the <deviceStateTable> element. 

The <actionList> element contains an < action > element for every 
action associated with the UPnP Service. The elements within an 

< action > element specify the name of the action and any arguments the 
action may take. In this case, the UPnP Service supports two actions that 

15 do not take arguments, ChannelUp and ChannelDown, and another, 
SetChannei, that takes a new channel number as an argument. The 

< argument > element and the elements nested within it define the 
argument. The <relatedStateVariable> element within <argument> 
specifies the name of one of the state variables to which the argument is 

20 related. In the UPnP Device Model, all arguments to actions must 
correspond directly to some state variable. 

Figures 1 9 and 20 show an XML schema for the SCPDL. 

Basic UPnP Eventing Architecture 

With reference to Figure 21, the UPnP architecture 200 (Figure 5) 
25 requires that clients of the UPnP API be enabled to receive notifications 
reliably from UPnP services 210-217 as their states change. Since state 
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changes are relatively common, the eventing subsystem's efficiency and 
performance is a major consideration in this design. Figure 21 and the 
following discussion describe the Basic UPnP Eventing Architecture 600, 
which encompasses both the controlled device (CD) 106 and user control 
5 point (UCP) 104 sides of the eventing UPnP Service. It also includes the 
support APIs for both a low-level UPnP Service interaction and a higher 
level COM-based wrapper of those APIs. The latter enables automation 
controllers like Visual Basic and JScript 602 to receive event notifications. 

What is an event? 

10 Property change events are defined as any change in the value of a 

row of the Device State Table (DST) 230 (figure 5) for a UPnP Service 
210-217. This change will be reflected as a property change notification. 
For example, if a "VCR" device has a "VCR Transport" UPnP Service, one 
row in that UPnP Service's DST may^e TapeState and the value could be 

1 5 TapePresent. If the tape is ejected, the new value would be TapeAbsent. 
This state change would be reflected as a notification sent to all 
subscribers. 

What is a notification? 

A UPnP event notification is an XML message sent over HTTP/TCP 
20 to each and every subscriber to a particular UPnP service. The content of 
the XML is defined below. The important contents of this message are the 
unique identifier for the subscription, the property name, new value, and 
property type. 
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Notification Processing 

In UPnP, the listener to Notifications is the SSDP service itself. 
SSDP already listens on another multicast address for "alive" and "byebye" 
messages sent by UPnP devices. The same listener will listen on a TCP 
5 port for notifications sent. All subscriptions sent from that UCP contain 
the same callback URL and so all notifications will be directed to that URL. 
When a notif ication arrives the SSDP service will examine the NT header of 
the message and determine if it is an event notification. If so, the message 
is parsed further to determine if it should be forwarded on to subscribers 
10 (which must exist). GENA defines the format of the HTTP message, what 
headers can be used, and what they can be used for. 

GENA 

GENA is the protocol of communication that, in a preferred 
embodiment, UPnP devices use to send event notifications. Therefore, 
1 5 UPnP devices that wish to notify UCPs of state changes are recommended 
to use GENA. Notification subscribers will never be required to interact 
with a UPnP device directly and so they are not required to use G€NA. The 
eventing API will encapsulate this complexity. Other appropriate event 
transport protocols may be used, such as publish/subscribe systems. 

20 Receiving Notifications 

Applications written in C (C Application 604) will be able to utilize 

the SSDP C API 610 to receive callbacks when notifications are processed 

by the SSDP service. This is analogous to SSDP clients registering for 

notifications that services have become available. When a UCP registers 

25 for -a notification, it passes as a parameter the URL of the UPnP Service for 

which it is interested in receiving notifications. This URL is obtained from 
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the description document for that UPnP Service. (When a UPnP Service is 
registered on a UPnP device, it uses this same URL to listen for 
subscription requests). 

When a notification message is received by the SSOP service 
5 listener, the SID header is checked against the list of subscribers it 

maintains. If a subscriber is found, the callback function for that subscriber 
is invoked, with one of the parameters being the contents of the 

notification message. The notification client that implements the callback 

■l 

function can process this message in any appropriate way. 

10 Notifications in the UPnP API 

The UPnP API 410 is a consumer of the basic C interface provided 

by the SSDP C API 610 component. In order to integrate seamlessly, the 

registration of notifications is handled by the Service Object 612 inside the 

UPnP Object Model. Service objects will register for notifications when 

1 5 they are created. This ensures that the DST is maintained by the UPnP API 

and is kept up to date. They will implement the callback function required 

by the registration function. If this callback function is invoked, it will pass 

on that notification to UCPs. The UGPs can be written in C, C + +, VB, or 

script code, so the mechanism for passing on notifications can be different. 

20 Script Support 

A feature of the illustrated eventing system is that it supports script 

languages such as VBScript and JavaScript 602. For VBScript, this is 

made possible by providing a property on the Service object that, when 

set, contains the IDispatch pointer for a VBScript function or subroutine 

25 that will be the event handler. When the Service object's notification 

callback is invoked, it checks to see if this IDispatch pointer was set, and if 
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so, it calls IDispatch::lnvoke on DISPID 0 of that interface to call the 
VBScript subroutine. An equivalent mechanism is implemented for JScript. 

Eventing Subsystem Terminology 

UCP - User control point. Any piece of software that searches for 
5 devices and controls them. 

CD - controlled device. A hardware or software device that 
announces its availability thru SSDP and allows control by UCPs. 

Subscriber - A UCP who wishes to be notified of event changes. 
Notifying Resource (or simply "Resource") - For the purposes of this 
10 document, this will always be a UPnP Service contained within a UPnP CD 
106. 

Event Source - a UPnP Service that provides events. UPnP -services 
are event sources. All notifying resources are event sources and vice 
versa. 

1 5 Event - message generated when a change in a resource's state 

occurs. 

Property - a single entry in the UPnP Service's state table whose 
DefaultValue can change. Properties and events always have a one to one 
correspondence. 

. » 

20 Subscribing To Resources 

Integrating With The UPnP API 

The UPnP API 410 exposes several interfaces with which a 
consumer can find and enumerate devices, control UPnP Services, and get 
properties on devices and UPnP Services. To allow the integration of 
25 events into this model, we add a new property to the lUPnPService 
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interface called EventHandler. When this property is set, it tells the Service 

object 612 that its client is interested in receiving notifications for that 

UPnP Service. The SSDP API RegisterNotificationO API is called when the 

Service object is created so that it can maintain a local copy of the DST for 

5 that UPnP Service. The Service object knows the URL of the UPnP Service 

and therefore it can provide this as a parameter to RegisterNotificationO. 

RegisterNotificationO is also provided a callback function which is a static 

member of the Service object class. This function will be invoked for each 

. .. . | 

and every notification sent by that particular UPnP service. 

r 

10 The Notification Callback 

The Service object 612 includes a static member function called 

Event Notify Callback 0 which is invoked for each notification sent by the 
UPnP service. The callback is passed the entire HTTP message contents in 
a structure which is a parameter to the function. The prototype looks like 
15 this: 

static VOID 

CUPnPService: : EventNotif yCallback ( SSDP_CALLBACK_ 
TYPE ssdpType, 
20 SSDP_MESSAGE *pssdpMsg, 

LPVOID pcontext) ; 

The ssdpType parameter should always be SSDPPROPCHANGE. 
The pssdpMsg parameter contains the relevant information about the 
25 event. The key piece of information is the body of the XML message. The 
body contains information about what property changed, what its new 
value is and what type it is, among other information. The pContext 
parameter will always be the this pointer of the Service object. This allows 
the code to call a method to fire the event to the UCP. The callback will 
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parse the XML body using the XML DOM services. Property changes are 

* * 

iterated and the local DST is updated to reflect these changes. After this 
processing is done, an event notification may be fired for each property 
that was changed to the owner of the subscription if one exists. 
5 Depending on what environment the owner is written in (C + + or script, 
etc.), a different mechanism for firing the event may be employed. 

A special case for this process is the very first notification received 
after a subscription is established. This notification contains the entire set 
of properties and their values and is used to locally sync up the DST. 
1 0 Events will not be fired to clients of the UPnP API in this case. 

Firing Notifications 

When the EventNotifyCaltbackO function is called, the local copy of 
the DST for the UPnP Service is updated. After this, an event needs to be 
fired if a subscriber exists. A subscriber exists if the putEventHandlerO 
15 method was called, either from VBScript, €+ + code, or another source. 
To abstract away this complexity, a new interface called lUPnPEvents is 
needed. 

This interface currently has one method called NotifyEventO which 
takes several parameters. When put_EventHandler() function is called, its 

20 argument is an lUnknown. This pointer is Querylnterface'dO for IDispatch 
first, and if it succeeds, then IDispatch::lnvoke() is called with DISPID 0 to 
invoke the default method. This allows VBScript 602 to be called. If that 
fails, however, it is Queried -for lUPnPEvents, and if that succeeds, the 
NotifyEventO method is called with the same parameters as for lnvoke(). 

25 The handles C+ + UCPs effectively. 
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Subscribing with C 4- + 

To subscribe to a UPnP service from C+ +, a UCP instantiates a 
UPnP service object, issues QuerylnterfaceO to it for lUPnPEvents, and 
calls the IUPnPEvents::SetEventCallback{) function. This function takes 2 
5 parameters, a callback function pointer and a context pointer. 

Subscribing With VBScript 

To subscribe to a UPnP service's events, all that needs to be done 

by a script 602 is to create a function or subroutine as a handler function 

f. 

and set the pointer of that function to the EventHandler property of the 
10 Service object. Now, anytime an ev^nt is fired, this VBScript function or 
subroutine will be called. In VBScript, this is written as the following: 

Dim UPnPAPI 

Set UPnPAPI = CreateObject P UPnPAPI . 1" ) 

15 

Devices - UPnPAPI . Find-Devices ( . . . ) 
For each device in Devices 

For each service In devices . services 
If service. dcpi = A> clock. vl" 
20 Service. EventHandler = 

-GetRef rclock_PropertyChang«d" ) 

End if 
Next service 
Next device 

25 

Sub clock_PropertyChanged (prop, value) 

MsgBox "The time has changed. It is now " & 
value & 
End Sub 

30 

In this example, the script enumerates all devices, looking for any 
device that supports the "Clock" interface. When it finds a device that 
supports that interface, it enumerates that device's UPnP Services looking 
for the one that has the "clock. vl " interface. Once it finds that UPnP 
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Service, it sets that service's EventHandler property to the VBScript 
subroutine called "clockPropertyChanged". This name is arbitrary. 

Sending and Receiving Notifications 
GENA Client API 

5 GENA clients are actually UPnP services. A GENA client creates a 

new event source when it is initialized. The GENA client API 620 
facilitates this. It also provides a way for GENA clients to send their 
notification messages. It is also important to note that the HTTP server 
that lives on the UPnP device is also a client of this API. The <3ENA client 
10 API consists of the following functions: 

RegisterUpnpEventSourceQ 

The RegisterUpnpEventSourceO API gives a GENA client the ability 

to register itself as an event source. The prototype is as follows: 

BOOL RegisterUpnpEventSource ( 
15 LPTSTR szRequestUri, 

DWORD cProps, 
UPNP_PROPERTY *rgProps 

); 

Parameters: szRequestUri {in] an arbitrary Request-Uri that 
20 SUBSCRIBE requests will be sent to. When a SUBSCRIBE request arrives 
at the given URI, it is acknowledged and the subscriber is added to the list 
of notification recipients. Note that this URI should match the URI provided 
in the description for this service. CProps fin] the number of properties 
that this event source provides. RgProps [in] Array of UPNPPROPERTY 
25 structures which contain information about each property. The property 
information is derived from the DST for the event source. 
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25 



Return Value: The function returns a TRUE if successful. If the given 
URL has already been registered as an event source, the return value is 
FALSE and GetLastErrorO returns E R R O R_ A LR E A D Y_EX I STS . 

Notes: The initial state of the event source needs to be given to the 
5 API so that it can effectively maintain the up-to-date state of the event 
source. 

DeRegisterUpnpEventSourceO 

The DeRegisterUpnpEventSourceO API gives a GENA client the 
ability to deregister itself as an event source. The prototype is as follows: 

10 VOID DeRegisterUpnpEventSource ( 

LPCTSTR szRequestUri 

) ; 

Parameters: szRequestUri lin] an arbitrary Request-Uri that 
15 SUBSCRIBE requests will be sent to. When a SUBSCRIBE request arrives 
at the given URI, it is acknowledged and the -subscriber is added to the list 
of notification recipients. Note that this URI should match the URI provided 
in the description for this UPnP Service. 

UPNP PROPERTY 

20 typedef struct _jUPNP_PROPERTY { 

LPTSTR szName; 
LPTSTR szValue; 
LPTSTR szType; 
} UPNP PROPERTY; 



Where szName is the name of the property, szValue is the current 
value of property, and szType is the type of property (string, integer, 
etc.). 
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SubmitUpnpPropertyEventQ 

The SubmitUpnpPropertyEventO API allows the GENA client to 



submit a UPnP property change event to be sent to subscribers as a 



notification. The prototype is as follows: 



5 



BOOL SubmitUpnpPropertyEvent ( 
LPCTSTR* szRequestUri, 
DWORD dwFlags, 



DWORD cProps, 



10 



UPNP_PROPERTY *rgProps 

>; 



Parameters: "szRequestUri tin]" identifies the event source to which 
this event belongs. This is the same Request-Uri passed to 
RegisterUpnpEventSourceO. "DwFlags [in]" is unused. "CProps {in]" is the 
15 number of events that are being submitted. "RgProps [in]" is an array of 
UPNPPROPERTY structures which contain information about each event. 

Return Value: If the function fails, the return value is FALSE. The 
get extended error information, call the GetLastErrorO function. 



20 notification, the local version of the property state for the given event 
source is updated with the list of properties passed in. 
SubmitUpnpPropertyEventO calls SubmitEventO after it has generated an 
XML body. 



Notes: When a series of properties is submitted for event 



25 



SubmitEventO 

The SubmitEventO API allows the GENA client to submit an 
unstructured event to be sent to subscribers as a notification. The 



prototype is as follows: 



30 



BOOL Submit Event ( 
LPCTSTR szRequestUri, 
DWORD dwFlags, 
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LPCTSTR szHeaders, 
LPCTSTR szEventBody 

); 

Parameters: SzRequestUri \\r\) identifies the event source to which 
5 this event belongs. This is the same Request-Uri passed to 

RegisterUpnpEventSourceO. DwFlags [in] Unused. SzHeaders [in] null- 
terminated text string containing the headers for the event, each separated 
by CRLF. SzEventBody [in] null-terminated text string containing the body 
of the event message 

10 Return Value: If the function fails, the return value is FALSC. The 

get extended error information, call the GetLastErrorO function. 

Notes: If no subscribers exist, the function does nothing. If one or 
more subscribers exist, a message is sent to each subscriber. 
SubmitEventO will always send to all subscribers. 

15 UPnP Controlled Device Event Architecture 

In UPnP, every UPnP service 210-21 1 that supports property change 

event notifications is to be a <3ENA client. Therefore, when the UPnP 
Service is initialized, it must register itself as a GENA event source. It will 
do this with the RegisterUpnpEventSourceO API. This returns a handle 

20 which can be used in subsequent APIs. 

RegisterUpnpEventSourceO talces a URL and an array of properties as 
parameters. Inside the API, an entry in an array of structures is initialized 
and the index is returned as the handle. The structure contains the source 
URL as one of the members. A second member of the structure, an array 

25 of destination URLs, is left uninitialized. This is filled in each time as 
subscriber is added for that event source. Another member of the 
structure is the list of properties that this event source provides. This is 
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effectively a cached copy of the DST for the event source. As events are 
submitted, the local properties are updated. 

When SubmitUpnpPropertyEventO is called, each property submitted 
replaces the corresponding property already maintained by the API. If no 
5 subscribers exist, the request to submit an event is ignored. If one or more 
subscribers exist, their callback URLs are looked up in the list of 
subscribers for the given event source and a NOTIFY message is 
constructed and sent to each URL, one at a time, in order of subscription. 
If an event is submitted and no response is received (or a CD-side 

10 error occurs), the CD continues to attempt to send to the UCP. If the 

subscription timeout expires, then the subscription is removed. If the UCP 
becomes available again, it will re-subscribe because it will notice the 
sequence numbers are not contiguous. 

When an HTTP server 626 receives a SUBSCRIBE message, it passes 

15 it along to a function which parses the message for the necessary 

information. The Request-URI identifies the UPnP Service that is to be 
subscribed to. The callback URL is obtained from the "Callback'" header. 
Since the Callback header can contain multiple URLs, it picks the first 
"http://" URL it finds. It then adds the subscriber to the list of subscribers 

20 for this event source. A unique subscription identifier is constructed which 
it will send back to the subscriber in the HTTP response to the SUBSCRIBE 
request. 

* 

If no event source matches the Request-URI from the subscription 
message, the HTTP server should return "404 Not Found". 
25 When a subscription is added, the local copy of the DST is sent as a 

NOTIFY message. This special NOTIFY message contains sequence 

. ■ 
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number 0 which informs the UCP that this is an initial state population 
event and not a notification where every event has changed. 

When a CD receives an UNSUBSCRIBE message, it checks the "SIC 
header to obtain the subscription identifier. It looks up the subscriber ID in 
5 the list of subscribers for that event source and removes the destination 
URL entry associated with it. 

GENA Server API 

GENA servers 630 are generally going toibe UPnP UCPs. A GENA 
server is anything that receives and processes NOTIFY messages to handle 
10 notifications from resources and sends SUBSCRIBE and UNSUBSCRIBE 

messages to receive notifications from resources. These APIs leverage the 
already existing SSDP APIs. The following are the changes to the APIs: 

RegisterNotificationO 

The RegisterNotificationO allows a UPnP UCP to request notification 
1 5 when an event occurs for a given UPnP service. The prototype is as 
follows: 

HANDLE RegisterNotif ication ( 

NOTI FY_TYPE nt, // SSDP_ALIVE | 

SSDP_PROPCHANGE | ?? 
20 LPTSTR szResourceType, // based on 

NOT I FY_T Y PE , unused if 

// SSDP_PR0PCHANGE is used. 

LPTSTR szEventUrl, 

ServiceCallbackFunc fnCallback, 
25 void *pContext 

)/ 

Parameters: Nt [in] An enumeration that determines the type of 
notification requested. The values are: SSOPALIVE - a UPnP Service has 
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become available, and SSDPPROPCHANGE - a property has changed on 
the UPnP Service. SzResourceType [in] A null-terminated string specifying 
the resource type desired. For SSDP_ALIVE, this is the service type, for 
SSDP_PROPCHANGE this is unused. SzEventUrl [inj A null-terminated 
5 string specifying the URL that a subscription request should be sent to. 
FnCallback [in] A pointer to a function that will be called each time a 
notification is received. The function pointer is defined in the SSOP spec. 
PCpntext [in] This parameter is included as a parameter when invoking the 
client-supplied callback function. 
1 0 Return Value: If the function succeeds, the return value is a handle 

used in a subsequent call to the DeregisterEventNotificationO function. If 
the function fails, the return value is INVALIDJHANOLE_VALUE error code. 
To get extended error information, call GetLastError. 

ServiceCallbackFunc 

15 typedef enum _SSDP_CALLBACK_TYPE { 

SSDP_FOUND = 0, 

SSDP_ALIVE = 1,. 

SSDP__BYEBYE = 2, 

SSDP_DONE - 3,. 
20 SSDP_PROPCHANGE = 4, 

} SSDP_CALLBACK_TYPE, * P S S D P_C ALL B AC K_T Y P E ; 

UPnP UCP Architecture . 

When a UPnP UCP wishes to subscribe to notifications for a 
25 particular UPnP service, it calls the RegisterNotificationf) API. It passes to 
this API a notification type that identifies the type of notification being 
requested, a URL to which a subscription should be sent, and a callback 
function and context for use when the notification is received. 
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RegisterNotificationO will compose a SUBSCRIBE message, using the 
data passed in, and send that to the URL specified by the caller. The 
Callback header of the SUBSCRIBE message will be composed on the fly, 
as an arbitrary URL for notifications to be sent to for this subscription. 
5 This callback URL will likely be a constant since the server API will always 
know how to handle requests sent to this URL. It will then send the 
SUBSCRIBE message and await a response. 

RegisterNotificationO in the SSDP API does not currently send HTTP 
requests, but it can be modified to do so. It also needs to await a response 
10 which it will also be modified to do so. 

When the response is received, the Subscription-ID header contains a 
SID which is associated with the callback function specified by the caller. 

Immediately after the response is received, the UCP should expect 
an initial NOTIFY message that contains the complete set of properties 
1 5 maintained by the CD. This becomes the local cached DST on the UCP 

side. From this point on, all modifications to the table are made via NOTIFY 
messages. This initial NOTIFY message will have sequence number 0 that 
indicates it is an initial property set and not an update. The UCP can use 
this information in any way it sees fit. This ensures the UCP's state table 
20 is always in sync with the one on the CD. 

4 * 

When a message is received by the HTTP server on the UPnP UCP, it 
is passed to a function which determines the method name and Request- 
URI. If this is a NOTIFY message, the headers are parsed and packaged up 
into a structure. The callback function that was specified to 
25 RegisterNotificationO is called with that structure as one of the parameters. 
UCPs who implement the callback function can find the headers and body 
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of the NOTIFY message and do additional processing based on the 
notification type. 

This all requires that the SSDP HTTP server listen on a TCP socket in 
addition to the UDP multicast port it already listens to. However, once a 
5 NOTIFY message is received/ it is processed in the same way regardless of 
from which connection it originated. 

* 

Handling Failures 

The following are subscription/notification failures that can occur and 
their solutions: 

10 Leaked Subscriptions 

To protect against subscriptions that exist on the controlled device, 
but no longer on the UCP, we institute the timeout feature of GENA 
subscriptions. The scenario is this: A UCP subscribes to a CD, then the 
UCP reboots. Meanwhile, the CD is still trying to send notifications to that 

1 5 UCP. If the UCP never comes back, the subscription would be leaked 

because the UCP never told the CD that it was going away. So to correct 
this, each subscription request includes an arbitrary timeout value which 
indicates to the CD that the UCP will be re-subscribing every n seconds 
indicated in the timeout header of the subscription request. If the timeout 

20 expires on the CD, the subscription is removed. The UCP is required to re- 
subscribe before the timeout period has elapsed. If it fails to do so, the 
subscription will be terminated by the CD. 

Some time before the timeout expires on the UCP, a re-subscribe 
message should be sent. The re-subscribe message is similar to the 

25 subscribe message, but it does not contain an NT or Callback header. If 
the UCP is unable to re-subscribe within the timeout period, the 
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subscription will be terminated by the CD. If the UCP sends a re-subscribe 
after the CD has terminated the subscription, the CD will return "412 
Precondition Failed". 

Reboot of a Controlled Device 
5 If a controlled device reboots, information about all of its subscribers 

would be lost. To prevent this, the subscriber information will be persisted 
across reboots of the device. Because the subscription info contains a 
timeout member, the absolute expiration time will be used when the 
subscription information is persisted. That way, when the device comes 
10 back up, it can check the timeout for each subscriber and if that time has 
passed, the subscription will be removed. 

Network Error Sending Event Notifications 

If a controlled device receives an error sending an event notification 
to a subscriber, it will NOT cease to send notifications. It will continue to 

1 5 send notifications and receive errors until the subscription expires. The 
problem for the UCP is that it will have missed a number of event 
notifications and so its state table will be out of sync. To correct this, 
each event notification message will contain a 32-bit sequence number that 
starts at 0 and increments for each message sent to a subscriber. If a 

20 subscriber receives a notification with a sequence number that is not 

exactly one more than the previous notification, it will know that it has lost 
events and will ignore all future notifications until it receives one with 
sequence number 0 again. Events with sequence number 0 indicate that 
the event is an "initial state" event. 

25 Once it realizes that is has lost one or more events, the UCP will 

send an UNSUBSCRIBE message, followed by a SUBSCRIBE message. This 
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is not the same as a re-subscription because re-subscriptions do not cause 
the CD to start the sequence over at 0. In this case, the active 
unsubscribe/subscribe will cause the CD to restart the sequence at 0 and 
send the entire state table with the first notification message. 

5 The SUBSCRIBE Message 

When a UPnP UCP wishes to subscribe to event notifications for a 

UPnP service 210-21 1, it will form a SUBSCRIBE message of the following 
format: 

SUBSCRIBE servicel HTTP/1.1 
10 Host: vcr. local : 200 

NT: . upnp: event 

Callback: <http: //remotel . local : 923/upnp> 
Timeout: Second-600 

15 The response is as follows:: 

HTTP/1.1 200 O.K. 

SID: uuid: kj 9d4f ae-7dec-lld0-a765-00a0c91e6bf 6 
Timeout: Second-600 

20 This example of a GEN A SUBSCRIBE request and response 

demonstrates a subscription to event notifications for "servicel." The host 
is "vcr. local." All notifications for this UPnP Service will be sent to the 
callback URL http://remote1 .local:923/upnp. In the response, the 
"Subscription-ID" header provides the subscriber with an identifier to use 

25 when it wants to unsubscribe to this resource. The "Timeout" header 

indicates that the subscriber will send a re-subscription request before 10 
minutes have elapsed. If the device does not receive this request within 
that period of time, it will remove the subscription. 
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The Re-SUBSCRIBE Message 

When a UPnP UCP wishes to re-subscribe to event notifications for a 
UPnP service, it will form a SUBSCRIBE message of the following format: 

SUBSCRIBE servicel HTTP/1.1 
5 Host: vcr. local : 200 

SID: uuid: kj 9d4 f ae-7dec-lld0-a765-00a0c91e6bf 6 
Timeout: Second-600 

The response would be as follows:: 

10 . HTTP/1.1 200 O.K. 

SID: uuid: kj 9d4f ae-7dec-lld0-a765-00a0c91e€bf 6 



Timeout : Second-600 



i 



Note that the NT and Callback headers are absent, but the SID 
1 5 header exists. This tells the CD 106 which subscription is being renewed 
and restarts the timeout. When the CD receives this message, it will 
persist the subscriptions to disk (or other persistent data storage medium), 
updating the absolute timeout based on the current time and a new timeout 
sent by the UCP (if it was different). 

20 The NOTIFY Message 

When a resource wishes to send an event notification, it will form a 
NOTIFY message of the following format: 

NOTIFY upnp HTTP/1.1 
25 Host: remotel. local: 923 

NT: upnp: event 
NTS: upnp:propertychanged 

SID: uuid: kj 9d4f ae-7dec-lld0-a765-00a0c91e6bf€ 
Seq: 123 

30 Content-Length: xxx 

Content-Type: text/xml 

<event XML schema> 

35 The response is as follows:: 
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HTTP/1.1 200 O.K. 

This example of a GENA NOTIFY request and response demonstrates 
that a "upnp:propertychanged" event is being sent to 
5 http://remote1 .local:923/upnp. The USN header identifies "vcr.servicel " 
as the event source. The XML contains the property name, value, and 
type. The "Seq" header indicates the sequence number of the notification. 
Sequence number 0 indicates the initial state update for the subscriber. 

Property Change Event XML Schema 
1 0 A UPnP property change event will be of the following form: 

<U:propertyset xmlns : U="upnp" > 

<U : propcount>2</U : propcount> 
<U:property> 
<U:foo> 

<U : type>string</U : type> 
goodbye 
</U:foo> 
</U : property> 
<U:property> 
<U:bar> 

<U : type>integer</U : type> 
27 

</U:bar> 
</U :property> 
</U : propertyset> 

Here, a property named "foo" is of type "string" and has a value of 
"goodbye" and a property named "bar" has a type of "integer" and has a 
value of 27. The XML will be contains a list of multiple properties that 
have changed, along with a count to make it easy to determine this. 
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The UNSUBSCRIBE Message 

When a UPnP UCP wishes to unsubscribe to event notifications for a 
UPnP service, it will form an UNSUBSCRIBE message of the following 
format: 

5 UNSUBSCRIBE servicel HTTP/1.1 

Host: vcr. local : 200 

SID: uuid: kj 9d4f ae-7dec-lld0-a765-00a0c91e6bf 6 

The response would be as follows:: 

10 HTTP/1.1 200 O.k. 

• ' " • .1 

This example of a GENA UNSUBSCRIBE request and response 
demonstrates that the UCP is no longer interested in receiving event 
notifications from http://vcr.local/service1 :200. 

15 Step By Step: UCP to CD & Back 

This section will take a step by step approach to what happens on 

both sides (UCP & CD) of an event notification. The description starts at 

the initialization of a UPnP device. Figure 22 illustrates the subscription, 

notification, and unsubscription process. 

20 

1 . A UPnP device called "vcr" initializes. 

a. It sets itself up to be an HTTP server by doing the following: 

i. It binds to a TCP socket using its IP address and an arbitrary 
port number. This address/port pair will be referenced by all 

25 incoming URL requests. 

ii. It listens for incoming connection requests on that socket and 
sets itself up to accept any incoming connections. 

b. It sets itself up to be an HTTP client by doing the following: 
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i. Calls InternetOpenO to get a handle to the internet session 

c. For each UPnP Service it exposes, it does the following: 

i. It calls the SSDP API RegisterUpnpEventSourceO to let the 
SSDP server know that it will be accepting subscriptions and 
5 sending event notifications. At this point, it has no 

subscribers. Note that this is called before the UPnP Service 
has announced itself so that it can be ready to accept 
subscriptions immediately. RegisterUpnpEventSourceO sends 
no network traffic on the wire. It is a local initialization only. 
10 RegisterUpnpEventSourceO does the following: 

1 . Adds a structure to the list of event sources containing 
the following: 

a. A URL to which subscribers will send subscription 
requests 

15 b. A list of destination URLs. A notification message 

will be sent to each destination URL. 
c.The state table for the event source. This structure 
contains the property name, value, and type for 
each property supported by the UPnP Service. 
20 ii. It calls the SSDP API RegisterServiceO to let the world know 

that it has become available. RegisterServiceO will send out an 
SSDP "alive" message on the multicast channel that will be 
heard by any device running the SSDP service. 

d. It starts sending events immediately, even without subscribers. 
25 Each event submission updates the local state table. This 

submission needs to be atomic with regard to adding subscribers, 
so between the time the SubmitEventO API is called, and the time 
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the local state table is updated, no subscriptions can be added or 
removed. 

2. Meanwhile, a UPnP UCP initializes. 

a. It initializes its HTTP server, passively listening on a TCP port. 
5 b. If the UCP started up before the UPnP device initialized, it won't 

see any services become available. When the device finally starts, 
the UCP will be notified, 
c. Once the UPnP services have been announced the UCP will be able 

i 

to access one or more of them. 1 
10 d. The UCP drives the UPnP API to instantiate a UPnP Service Object. 

e. The UPnP Service Object does the following when it is 
instantiated: 

i. It obtains the event subscription URL from the description for 
that service. 

1 5 ii. It calls the SSDP API RegisterNotificationO specifying 

SSDP_PROPCHANGE as the event type, the event subscription 
URL, a callback function pointer (which is a static member 
function of the class), and a context pointer (which is the 
"this" pointer of the class). RegisterNotificationO does the 

20 following: 

1. It makes an LRPC call to the SSDP service. The rest 
happens on the service side. 

2. If this is the first time it is called for 
SSDP_PROPCHANGE notifications, RegisterNotificationO 

25 will call InternetOpenO to get a handle to an internet 

session. This handle is shared among all local UPnP 
UCPs. 
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3. It calls InternetConnectO passing the server name given 
in the URL it was passed. 

4. It calls HttpOpenRequestO passing in the rest of the URL 
it was passed. 

5. The handles returned by these functions are saved with 
the structure that maintains the subscription. 

6. It composes a SUBSCRIBE message, using the data 
passed in, by calling HttpAddRequestHeadersO. It adds 
the "NT", "Callback", and "Timeout" headers. The 
Callback header of the SUBSCRIBE message will be 
composed on the fly, as an arbitrary URL for notifications 
to be sent to for this subscription. The server name is the 
local IP address, and the port is the same one referred to 
by step 2a above. 

7. It calls HttpSendRequestO to send the request to the 
CD. This is a synchronous function that will return when 
the request has been responded to by the CD. 

8. It calls HttpQuerylnfoJ..., HTTP_QUERY_CUSTOM, ...) to 
get the "Subscription-Id" header. The resulting SIO will 
be stored with the subscription structure. 

9. It calls HttpQueryinfo(.„ HTTP_QUERY_CUSTOM, '„.) to 
get the "Timeout" header. The resulting timeout value 
will be stored with the subscription structure. 

10. A timer is started for re-subscription based on the 
timeout value returned in the response. When the timer 
goes off, the re-subscription will be sent. 
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11. The SID, callback function pointer, and timeout 
values are stored in a structure that maintains the list of 
local subscriptions. 
3. Back on the UPnP CD, the subscription request is received by the HTTP 
5 server. The following occurs: 

a. The request is parsed into URI, NT, Callback, and Timeout fields. 

b. The NT field must match "upnp.event". If it doesn't, the CD 
responds with "412 Precondition Failed." 

c. The URI identifies the event source. Tlie URI is -converted into a 
10 URL and matched with the list of event sources registered on the 

* 

CD. If no match is found, the CO responds with "404 Not Found". 

d. If a match is found, the following occurs: 

i. The Callback URL is added to a list of subscriber URLs. 

ii. The Timeout value is processed and an absolute time is stored 

> » 

15 with the event source data. If this time expires and a re- 

subscribe message has not been received, the subscription is 
removed. 

iii. A new SID is created, and stored with the subscriber in the 
event source. 

20 iv. A sequence number is initialized to 0. 

v. A subscription response is composed, including an echo of the 
Timeout header and the SID just created. 

vi. The response is sent. 

vii. If the response is sent successfully, the list of event sources is 
25 persisted to disk for recovery purposes. 

viii. A timer is started using the same timeout value as the header 
echoed to the UCP. When this timer elapses, the subscription 
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is removed. If the CD receives a re-subscribe request, this 
timer will be reset. In an ideal world, the timer will never 
elapse. 

An initial event notification is sent to initialize the UCP's state 
table. The following describes that process: 

1 . InternetOpenO is called if an existing internet session 
handle does not exist. 

2. InternetConnectO is called, passing the server name 
specified in the callback URL for this subscription. 

3. HttpOpenRequestO is called, passing in the rest of the 
callback URL 

4. A NOTIFY message is composed, using the data passed 
in, by calling HttpAddRequestHeadersO. It adds the "NT" 
"NTS", "SID", "Seq", "Content-Length", and "Content- 
Type" headers. 

a. The NT header will always be "upnprevent". The 

NTS header will always be "UPnPrpropertychange". 

b. The SID header contains the SID stored in the 
event source structure 

c. The Seq header will always be 0. 

d. The Content-Length header will be the number of 
bytes in the XML body. 

e. The Content-Type header will always be "text/xml". 

f . The body of the message is composed from the list 
of properties stored within the event source 
structure: 

i. Write the < propertyset > opening tag. 
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ii. Write the <propcount>/7</propcount> tag. 
Where n is the number of total properties. 

iii. For each property: 

1. Write the < property > opening tag. 
5 2. Write the <prop> opening tag, where 

prop is the name of the property. 
3. Write the <type> fype</type> tag, 
where type is the stringized type name of 
the property type. 
10 4. Write the property value. 

5. Write the < /prop > closing tag. 

6. Write the < /property > closing tag 

iv. Write the </propertyset> closing tag 

5. It calls HttpSendRequestExO, then InternetWriteFileO, 
1 5 then HttpEndRequestO to send the request to the CD. 

6. The response is ignored except for debugging purposes. 
4. The UPnP CD now is ready to send an event notification. It does this by 

calling the SubmitUpnpPropertyEventO API. The following occurs inside 
that API: 

20 a. The event source handle is converted to an event source structure. 

b. The properties that have changed as a result of the event are 
passed into the function and updated in the local list of properties 
stored with the event source. 

c. For each subscriber, the following occurs: 

25 i. InternetConnectO is called, passing the server name specified 

in the callback URL for this subscription. 
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HttpOpenRequestO is called, passing in the rest of the callback 
URL 

A NOTIFY message is composed, using the data passed in, by 
calling HttpAddRequestHeadersI). It adds the "NT", "NTS", 
"SID", "Seq", "Content-Length", and "Content-Type" headers. 

1 . The NT header will always be "upnprevent". The NTS 
header will always be "UPnPiprppertychange". 

2. The SID header contains the SID stored in the event 
source structure 

3. The sequence number for the event source is 
incremented and the Seq header is created with this 
value. 

4. The Content-Length header will be the number of bytes 
in the XML body. 

5. The Content-Type header will always be "text/xml". 

6. The body of the message is composed from the list of 
properties stored within the event source structure: 

a. Write the <propertyset> opening tag. 

b. Write the <propcount>n</propcount> tag. 
Where n is the number of total properties. 

c. For each property that has been submitted: 

i. Write the < property > opening tag. 

ii. Write the <prop> opening tag, where prop is 
the name of the property. 

iii. Write the < type > type < /type > tag, where 
type is the stringized type name of the 
property type. 
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iv. Write the property value. 

v. Write the <lprop> closing tag. 

vi. Write the < /property > closing tag 
d. Write the < /property set > closing tag 

5 iv. SubmitEventO is called, passing the event source handle, the 

handle to the headers created by 4c(i) thru 4c(iii) above, and 
the body created in step 4c(iii)6. SubmitEventO does the 
following: 

1 . It calls HttpSendRequestEx(i, then lnternetWrite1=ile() on 
10 the body, then HttpEndRequestO to send the request to 

the CD. 

* 

2. The response is ignored except for debugging purposes. 
5. The UPnP UCP receives the notification message. The message is 

processed as follows: 
1 5 a. The HTTP server receives a NOTIFY message with a Request-URI 

and several other headers, 
b. The NOTIFY message is parsed, looking at the "NT" header first. If 
this header contains "upnp:event", then the message is further 
processed for event notifications as follows: 
20 i- The message is parsed for the NTS header. If that contains 

"upnp:propertychanged", then the message is parsed further 
as follows: 

1 . The message is parsed for the SID header. The SID 
indicates to the UPnP control point which subscription 

25 this message applies to. 

2. The message is parsed for the "Seq" header. If this 
header contains a value of 0, the UCP knows this is an 
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initial state populate request. If the local sequence 
number is exactly one less than the Seq header, the local 
sequence number, is updated (incremented), and the 
message is processed further. 

3. The Request-URI can be ignored, since the HTTP server 
knows all NOTIFY messages with an NT header of 
"upnprevent" are sent to the same Request-URI. 

4. If the Seq header contains a number that is not exactly 
one more than the local sequence number, the UCP 
knows it has missed an event. In this state, it needs to 
unsubscribe and re-subscribe to the event source in order 
to re-sync its state. 

5. The SID is matched against the list of subscriptions 
maintained on the UCP. When the SID is matched, its 
associated callback function is invoked. 

6. The callback function is passed an SSDPJVIESSAGE 
structure which contains all the relevant headers and the 
body of the XML message received. 

7. The callback function is implemented by the UPnP API, 
as a static member of the Service object. When this 
function is called, the following occurs: 

* 

a. The body of the message is parsed using the XML 
DOM services. 

b. As properties are enumerated, their values are 
stored in the local state table for the UPnP Service. 
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c. An event is fired to all high-level clients of the UPnP 

API. This event contains the list of properties that 
have changed and their new values. 
6. The re-subscription timer for one of the UCPs subscriptions expires. The 
5 following occurs: 

a. A re-subscribe message is composed. This message is very similar 
to a subscribe message except in doesn't include an NT or Callback 
header, but it does have a SID header. 

b. The request is sent to the CD. 1 

10 c. The response contains the new timeout value. 

d. The timer is reset with this timeout. 

* » 

UCP State Synchronization Models 

CD-Initiated NeedsSync method 

This method begins with the CD sending its initial state to the 
1 5 subscriber the first time an event is submitted by the UPnP Service. UCPs 
will subscribe to the UPnP Service first, then receive notifications for 
events as they occur. The first event will happen to be the initial state of 
the UPnP Service. The UCP state table will always be in sync with this 
method. 

20 When the CD sends a notification to a subscriber and receives an 

error. In this case, it marks the subscriber as "NeedsSync" and the next 
time an event is submitted, all events are sent to the subscriber. The 
problem with this is that the API needs to keep track of which subscribers 
need syncing and which ones don't. The client of this API (the UPnP 

25 service) would need to send separate messages to each subscriber and 
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know which ones needed all events and which ones just wanted the ones 
that changed. 

UCP-initiated sync 

This method states that the UCP should subscribe to event 
5 notifications, then call a function that obtained the state from the UPnP 
Service. This means that any events that were received in the meantime 
would need to be matched against the incoming set of events and replaced 
if they were older. This method leads to synchronization issues where the 
UCP may receive events that are newer but when it queries for the state, it 

10 gets an older view of the table. This requires using sequence numbers to 
determine which information is newer. If the view of the table received by 
the query is too old, it has to be discarded. Alternatively, the properties 
that were not received by event notification would not be overwritten, but 
all other properties would be. Using sequence numbers make this more 

15 complicated. 

CD-initiated sync 

This preferred method takes a simpler approach. Any time the UCP 
subscribes to a UPnP Service, the UPnP Service will immediately 
afterwards, send the entire contents of the state table with the first 

20 notification. This precludes the UCP from making a query for the state 
table. Subsequent events update the local state table on the UCP. If the 
connection is lost, the UCP will lose its subscription. If the UCP realizes it 
has not received an event after a certain amount of time has elapsed, it will 
re-subscribe. At that point, the CD will re-send the entire state table again, 

25 and the UCP is ensured to be up to date. 
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Exemplary Computer Hardware 

Figure 23 and the following discussion are intended to provide a 
brief, general description of a suitable computer which may be used in the 
above described UPnP device control model. This conventional computer 
5 820 (such as personal computers, laptops, palmtops or handheld-PCs, set- 
tops, servers, mainframes, and other variety computers) includes a 
processing unit 821, a system memory 822, and a system bus 823 that 
couples various system components including the system memory to the 
processing unit 821 . The processing unit may be any of various 
1 0 commercially available processors, including Intel x86, Pentium and 

compatible microprocessors from Intel and others, including Cyrix, AMD 
and Nexgen; Alpha from Digital; MIPS from MIPS Technology, NEC, IDT, 
Siemens, and others; and the PowerPC from IBM and Motorola. Dual 
microprocessors and other multi-processor architectures also can be used 

* 

15 as the processing unit 821. 

The system bus may be any of several types of bus structure 
including a memory bus or memory controller, a peripheral bus, and a local 
bus using any of a variety of conventional bus architectures such as PCI, 
VESA, AGP, MicroChannel, ISA and EISA, to name a few. The system 

20 memory includes read only memory (ROM) 824 and random access 

memory (RAM) 825. A basic input/output system (BIOS), containing the 
basic routines that help to transfer information between elements within 
the computer 820, such as during start-up, is stored in ROM 824. 

The computer 820 further includes a hard disk drive 827, a magnetic 

25 disk drive 828, e.g., to read from or write to a removable disk 829, and an 
optical disk drive 830, e.g., for reading a CD-ROM disk 831 or to read from 
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or write to other optical media. The hard disk drive 827, magnetic disk 
drive 828, and optical disk drive 830 are connected to the system bus 823 
by a hard disk drive interface 832, a magnetic disk drive interface 833, and 
an optical drive interface 834, respectively. The drives and their 
5 associated computer-readable media provide nonvolatile storage of data, 
data structures, computer-executable instructions, etc. for the computer 
820. Although the description of computer-readable media above refers to 
a hard disk, a removable magnetic disk and a CD, it should be appreciated 
by those skilled in the art that other types of media which are readable by a 

10 computer, such as magnetic cassettes, flash memory cards, digital video 
disks, Bernoulli cartridges, and the like, may also be used in the exemplary 
operating environment. 

A number of program modules may be stored in the drives and RAM 
825, including an operating system 835, one or more application programs 

1 5 836, other program modules 837, and program data 838. 

A user may enter commands and information into the computer 820 
through a keyboard 840 and pointing device, such as a mouse 842. Other 
input devices (not shown) may include a microphone, joystick, game pad, 
satellite dish, scanner, or the like. These and other input devices are often 

20 connected to the processing unit 821 through a serial port interface 846 
that is coupled to the system bus, but may be connected by other 
interfaces, such as a parallel port, game port or a universal serial bus 
(USB). A monitor 847 or other type of display device is also connected to 
the system bus 823 via an interface, such as a video adapter 848. In 

25 addition to the monitor, computers typically include other peripheral output 
devices (not shown), such as speakers and printers. 
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The computer 820 operates in a networked environment using 
logical connections to one or more remote computers, such as a remote 
computer 849. The remote computer 849 may be a server, a router, a 
peer device or other common network node, and typically includes many or 
5 all of the elements described relative to the computer 820, although only a 
memory storage device 850 has been illustrated in Figure 23. The logical 
connections depicted in Figure 23 include a local area network (LAN) 851 
and a wide area network (WAN) 852. Such networking environments are 
commonplace in offices, enterprise-wide computer networks, intranets and 
10 the Internet. 

When used in a LAN networking environment, the computer 820 is 
connected to the local network 851 through a network interface or adapter 

853. When used in a WAN networking environment, the computer 820 
typically includes a modem 854 or other means for establishing 

15 communications (e.g., via the LAN 851 and a gateway or proxy server 
855) over the wide area network 852, such as the Internet. The modem 

854, which may be internal or external, is connected to the system bus 
823 via the serial port interface 846. In a networked environment, 
program modules depicted relative to the computer 820, or portions 

20 thereof, may be stored in the remote memory storage device. It will be 

appreciated that the network connections shown are exemplary and other 
means of establishing a communications link between the computers may 
be used. 

In accordance with the practices of persons skilled in the art of 
25 computer programming, the present invention is described below with 
reference to acts and symbolic representations of operations that are 
performed by the computer 820, unless indicated otherwise. Such acts 
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and operations are sometimes referred to as being computer-executed. It 
will be appreciated that the acts and symbolically represented operations 
include the manipulation by the processing unit 821 of electrical signals 
representing data bits which causes a resulting transformation or reduction 
5 of the electrical signal representation, and the maintenance of data bits at 
memory locations in the memory system (including the system memory 
822, hard drive 827, floppy disks 829, and CD-ROM 831) to thereby 
reconfigure or otherwise alter the computer system's operation, as well as 
other processing of signals. The memory locations where data bits are 

10 maintained are physical locations that have particular electrical, magnetic, 
or optical properties corresponding to the data bits. 
Exemplary Embedded Computing Device 

Figures 24 and 25 are intended to provide a brief, general description 
of a suitable embedded computing device 900 which may be used in the 

15 illustrated implementation of the invention. The embedded computing 

device 900 can be any variety of device incorporating electronics to control 
operational functions (operational circuitry 906), and in which computing 
and networking capabilities are embedded. For example, devices in which 
computing and networking functions can be embedded include 

20 communications devices (e.g., telephones, cell phones, audio and video 
conferencing systems, 2-way radios, etc.), office equipment (printers, fax 
machines, copiers, dictation, etc.), audio-video equipment (audio and video 
recorders and players, including televisions, radio receivers, compact disk 
(CD), digital video disk (DVD), camcorders, etc.), entertainment devices 

25 (set-top boxes, game consoles, etc.), environment control equipment 

(thermostats, heating/ventilation/air-conditioning equipment, light switches, 
etc.), security systems, home appliances (coffee makers, dishwashers, 
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clothes washer/dryer), automobiles, public facilities equipment (signs, 
traffic signals, etc.), manufacturing equipment, and many others. 

With reference to Figure 24, the device 900 includes a processing 
unit 902, and a memory 904 to provide embedded computing capability. 
5 The processing unit 902 has hardware interfaces to the operational 

circuitry 906 that operates devices functions. The processing unit 902 can 
be a microprocessor or micro-controller, such as are available from Intel, 
Motorola, IBM, and others. The memory 904 preferably incorporates RAM 
and ROM to hold software and data for basic operating code as well as for 

10 user applications. 

The device 900 also includes a network adapter 908 for connecting 
with a network media 910 that is interconnected with the computer 
network in which the authoritative names registry (described below) is 
implemented in accordance with the invention. The network adapter 908 

1 5 can be a network interface card (or chip set integrated on a single board 
with the processing unit 902) appropriate to the particular network media 
910. The network media can be any of various wired or wireless network 
media, including Ethernet, IEEE 1394 (a.k.a. firewire), radio frequency 
(including satellite, cell, pager, commercial signal sideband, etc.), power 

20 line carrier (PLC), phone line, and television cable, among others. 

With reference now to Figure 25, the embedded computing device 
100 (Figure 24) has a software architecture 120 that -conforms to the 
above described UPnP device control model. UPnP provides a mechanism 
for the embedded computing device to operate in the Internet, as well as 

25 networks that have no administrator and no connection to the Internet, and 
hence no access to configuration services like the Dynamic Host 
Configuration Protocol (DHCP). DHCP is a mechanism for providing 
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devices with configuration information needed to access the Internet. The 
mechanism functions through the use of a multicast request for 
configuration information that is generally responded to with an IP address 
and DNS server location. Additional information can only be returned in the 
5 response. 

In non-configured (ad-hoc) networks, UPnP uses the AutolP protocol. 
AutolP is an enhancement to DHCP that allows devices to claim IP 
addresses in the absence of a DHCP server or similar IP configuration 
authority. IP addresses are claimed from a reserved range that is not 

10 allowed to be transmitted on the open Internet; thus they are only good for 
the local network. The embedded computing device 100 claims an address 
by randomly generating an address in the reserved range and then making 
an ARP request to see if anyone else has already claimed that address. 
AutolP systems will continually check for the presence of a DHCP server so 

1 5 that if one should ever come online, all the AutolP devices will attempt to 
switch their IP addresses to one provided by the DHCP server. This allows 
a network to operate in isolation, be connected to the Internet with DHCP 
support and then to be returned to isolation. This type of scenario will be 
common in homes that use dial-up access. 

20 UPnP implements a peer discovery mechanism that uses the Simple 

Service Discovery Protocol (SSDP) for discovery of devices on IP networks. 
SSDP is based on profiles. A single identifier specifies a profile that defines 
a contract between the client and UPnP Service (e.g., operational functions 
provided by the embedded computing device). By identifying itself with 

25 the profile, the UPnP Service advertises compliance with the associated 
contract. 
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Using a single identif ier makes it possible to implement an -extremely simple 
discovery system. Clients send out a User Datagram Protocol (UDP) 
multicast packet containing the identifier of the desired UPnP Service on 
some standard channel. UPnP Services listen on the standard channel, 
5 read the request, see whether they provide the UPnP Service, and respond 
if so. 

UPnP also provides a Directories mechanism to allow discovery to 
scale - to the entire Internet if needed. When present, a directory will read 
all incoming service requests and respond to tliem itself. This requires that 

10 all UPnP Services (e.g., the embedded computing device 900) register with 
the directory so that the directory is able to properly answer on their 
behalf. The directory is also responsible for communicating with other 
directories in order to determine whether the UPnP Service is available 
within the local network, the WAN and potentially the Internet. 

15 To simplify the discovery protocol, directories are treated as proxies. 

A proxy is a service that accepts requests and takes responsibility for 
finding the proper response. When a client comes online, it will perform 
discovery for the proxy. If the proxy is present, then the client will send all 
future discovery requests to the proxy. If the proxy isn't present, then the 

20 client will send all discovery requests to the reserved discovery multicast 
channel. Regardless of the presence of a proxy, the client's request format 
and procedures will always be the same. The only difference will be the 
address to which the client sends its requests. For UPnP Services, the 
difference between a proxied and unproxied network is their need to 

25 answer discovery requests. On a proxied network, UPnP Services need do 
nothing once they have registered with the proxy. On an unproxied 
network, they answer discovery requests directly. 
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SSDP uses the UDP- and Transmission Control Protocol (TCP)-based 
Hyptertext Transport Protocol (HTTP) to provide for service discovery. 
SSDP uses a Uniform Resource Identifier (URI) to represent the service and 
the OPTIONS method to provide for discovery. SSDP also will provide 
5 support for proxies. These proxies, which are really just fronts for 

directories, redirect discovery requests to themselves. It is the proxy's job 
to collect announce requests in order to determine what UPnP Services are 
available as well as to communicate with other proxies in order to provide 
for scalable service discovery. 

10 The discovery process returns only the basic information needed to 

connect to the embedded computing device. Once a UPnP Service has 
discovered its peers, the UPnP Service often needs to find out more 
information in order to work best with them. The description process 
returns a schema providing descriptive data about the UPnP Service. 

15 A schema is a structured data definition that defines a set of 

structured values that provide descriptive information about a UPnP 
Service. UPnP uses the Extensible Markup Language (XML) for schema, 
because XML-s self-describing structured data format provides the level of 
expressiveness and extensibility needed by a universal schema and data 

20 format. 

Accordingly, UPnP supports automatic network introduction, 
meaning that devices and their related UPnP Services have the ability to be 
self-describing and allow automatic configuration. When a device is 
plugged into the computer network, the device automatically configures 
25 itself and acquires a TCP/IP address. The device then announces its 

presence to other devices already on the network using a simple discovery 
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protocol based on the Internet HTTP protocol and is immediately ready to 
share its UPnP Services with any device that requests them. 

With UPnP, device developers are not required to develop specific 
device drivers to operate under UPnP. The task of preparing a device for 
5 operation in this network environment thus is fairly simple. Moreover, in 
configured networks, dynamic detection allows an operating system to 
immediately begin using added devices or stop using removed devices 
without rebooting. 

* 

UPnP Devices support automatic discovery, identification, and 
10 configuration to achieve interoperability in the home environment, but must 
also operate correctly in a managed corporate network. Devices can be 
networked instead of being attached directly to a PC, and devices are all 
autonomous citizens on the network, able to talk with each other and 
exchange information. UPnP provides a unified way of performing 
15 directory services with automatic configuration. Capability for simple 

discovery mechanism used in the home environment provides the ability for 
any device to become a node on the global Internet. Additionally, directory 
services can be leveraged if they are available in the corporate 
environment. 

20 UPnP provides a common set of interfaces for accessing devices and 

UPnP Services, enabling the operational unification of diverse media types. 
Communications protocols for Universal Plug and Play are based on 
industry standards, especially key Internet standards such as TCP/IP, 
HTML, XML, HTTP, DNS, LDAP, and others. Individual implementations 

25 for particular networks and buses are built on established protocols. 

As shown in Figure 25, the software architecture 920 of the 
embedded computing device 900 (Figure 24) includes the following 
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software code modules that implement UPnP: device functions 922, simple 
discovery 924, Hypertext Transport Protocol (HTTP) 925, Transmission 
Control Protocol/Internet Protocol (TCP/IP) stack 926, Dynamic Host 
Configuration Protocol (DHCP) with AutolP extension 928, Domain Name 
5 System (DNS) with Multicast DNS extension 930, and physical media 910 
(also shown in Figure 24). The device functions 922 is a software code 
module to implement the device's functionality. For example, where the 
embedded computing device is a VCR, the device functions code can 
include code to implement start, stop, pause, record and other functions 

10 that the VCR can perform. 

The simple discovery 924 is a software code module (about 4 
Kbytes) that implements a simple discovery procedure (described below) 
for automatic network introduction under the UPnP protocol. 

The simple discovery procedure additionally provides an Extensible 

15 Markup Language (XML) format device description, which is downloaded to 
clients that access the device to allow activation of device functionality 
from the client. XML is a textual, tag-based markup language. It was 
originally designed to be the "Webby" simplification of SGML (Standard 
Generalized Markup Language), and is therefore intended to be used to 

20 create "vocabularies" of tags that can be used to apply semantic markup to 
documents, such as who the author was, what constitutes a paragraph 
(semantically, not from a display point of view), when the author last had 
breakfast, and so on. (For more information, see A. Layman, E. Jung, E. 
Maler, H. Thompson, J. Paoli, J. Tigue, N. H. Mikula, S. De Rose, XML- 

25 Data , W3C Note 05 Jan 1998.) In the context of UPnP, XML is used to 
provide the description of UPnP Services and capabilities of the embedded 
computing device. The embedded computing device makes its features 
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visible to clients by providing its XML device description, which the client 
can use to activate device functions 922. For example, if the device is a 
camera, the client's browser can direct the camera to zoom in/out or adjust 
contrast using the mechanism of XML. 
5 The XML device description can provide links (via a uniform resource 

locator or URL address) to an accompanying XSL format style sheet. The 
XSL style sheets are used to present the data in different ways, i.e., the 
style sheets are applied to present different views of the same data. For 
example, if the device contains a file system, one style sheet can show the 

10 file selections; another shows the file sizes in some sort of diagram; yet 
another style sheet could make thumbnails of these image files. 

The HTTP 925 is a software code modules (about 20 Kbytes) that 
implements the standard HTTP protocol, which is an open standard 
mechanism for client/server message-based communication. HTTP 

15 provides for proxying, content negotiation and security. (For more 

information, see R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. Berners- 
Lee, Hypertext Transfer Protocol - HTTP/1.1 , IETF RFC 2068 (January 
1997).) 

The TCP/IP stack 926 implements the standard TCP/IP networking 
20 protocols for communication on the computer network. The Internet 

Protocol (IP) is the foundation protocol of the Internet. It defines how a 
single message is sent from a source through zero or more routers to its 
final destination. It covers issues such as message length, message 
fragmentation, addressing, and routing concerns. The Transmission 
25 Control Protocol (TCP) is an IP-based protocol that provides support for the 
reliable, ordered delivery of messages over IP. Additionally, User Datagram 
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Protocol (UDP) and Internet Group Management Protocol (IGMP) multicast 
send/listen capability are included in the implementation. 

The AutolP 928 is a software code module also used for automatic 
network introduction via AutolP in the UPnP protocol. AutolP uses a 
5 predefined set of IP addresses and, when a device is connected to the 

network, it pings an address in this address space. If it gets no replies, the 
device assumes that the address is available and assigns it to itself. An IP 
Multicast is a mechanism for sending a single message to multiple 
recipients. IP multicasting is especially useful for discovery operations 

10 where one does not know exactly who has the information one seeks. In 
such cases, one can send a request to a reserved IP multicast address: 
Any UPnP Services that can provide the requested information will also 
subscribe to the multicast request and thus be able to hear the information 
request and properly respond. 

1 5 The DHCP 930 is a software code module that implements the 

Dynamic Host Configuration Protocol (DHCP), which is a mechanism for 
providing devices with configuration information needed to access the 
Internet. The mechanism functions through the use of a multicast request 
for configuration information that is generally responded to with an IP 

20 address and DNS server location. Additional information can only be 
returned in the response. 

Figures 26 and 27 show processes 934, 940 per the UPnP protocol 
for automatic network introduction of the embedded computing device 900 
(Figure 24) into an ad hoc (where the device does not have a configured IP 

25 address) and a configured computer network environment, respectively. 
The automatic network introduction process establishes an appropriate 
configuration (e.g., with an IP address) of the embedded computing device 
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upon connection to a server computer on a computer network, so as to 
enable access to the device from a client. The processes 934, 940 involve 
five phases: AutolP, announce, discovery, response to discovery, and 
device description. 

5 At the announce phase, the embedded computing device 900 sends 

out a small multicast packet so that other devices can find it on the 
network. The multicast message packet essentially says, "I am here, I am, 
(say), a camera, and you can reach me at this IP address or URL." 

At the discovery phase, the embedded computing device 900 listens 

10 for a discovery packet coming from a simple discovery client, i.e., the 

device announces itself, then listens for discovery. The discovery packet 
also is sent out by multicast. 

At response to discovery, the embedded computing device 900 
listens to the multicast address and then parses the information from a 

1 5 Simple Discovery request to decide if the request is for its kind of device. 
If so, the device 1 00 then sends back a response packet containing the 
following information: the IP address or URL where it can be reached; 
identification of its own device type; and the discovery packet ID so the 
requesting client knows which request is being answered. 

20 At the AutolP phase, the AutolP module 928 of the embedded 

computing device 900 uses a predefined set of IP addresses and, when the 
device is connected to the network, it pings an address in this address 
space. If no reply is received, the device 900 assumes that the address is 
available and assigns it to itself. 

25 Both the Announce and Discovery packets also contain a link or a 

URL to an XML file that is used by the embedded computing device at the 
device description phase to describe itself (i.e., its functionality). This XML 
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data contains all the facts about the device. XML can also have URLs that 
point to appropriate style sheets (XSL files) that are used for optimal 
presentation. The XSL style sheets are used to present the data in 
different ways, i.e., the style sheets are applied to present different views 
5 of the same data. For example, if the device contains a file system, one 
style sheet can show the file selections; another shows the file sizes in 
some sort of diagram; yet another style sheet could make thumbnails of 
these image files. 
Exemplary Client 

« 

10 With reference now to Figure 28, a client that accesses and uses the 

embedded computing device 900 over the computer network has an 
exemplary client software architecture 950, which includes software code 
modules for applications 952, simple discovery 954, XML 955, LDAP 956, 
TCP/IP stack 958 and a network interface card (NIC) 960 that provides a 

1 5 physical connection to the computer network. The applications 952 is a 
software code module that provides a user interface features for locating 
desired devices (e.g., embedded computing device 900) and UPnP Services 
on the computer network, and also user interface features to interact with 
the located device or UPnP Service. The applications 952 can include an 

20 Internet browser, such as the Microsoft Internet Explorer, that can present 
the XML device description in accordance with an associated XSL style 
sheet for interaction with the embedded computing device and activation 
of its operational functionality. 

The simple discovery 954 is a module that implements the above- 

25 described simple discovery per the UPnP protocol. The XML 955 is a 

module that processes the XML device description and XSL style sheets for 
presentation in the application's user interface. The LDAP 956 implements 
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958 implements the TCP/IP protocol for communications over the computer 
network. 

Illustrative Pervasive Computing Environment 
5 Figure 29 illustrates a pervasive computing environment 1000, such 

as may be installed in a home, office or public place, which includes a large 
number of embedded computing devices, such as the illustrated device 900 
(Figure 24). The pervasive computing environment 1000 includes personal 
computers 1002, 1004 (e.g., of the type shown in Figure 23) connected 

10 via a local area network (LAN) 1006. The PC 1002 is connected via a 
universal serial bus 1016 to a telephone modem 1010, XDSL interface 
101 1 or a cable modem 1012, which in turn provide a connection with the 
computer network, e.g., the Internet. 

Various embedded computing devices also connect to the computer 

15 network via various network connections to the PCs 1002, 1004. These 
include an audio device 1014 (e.g., speakers, radio tuner, microphone), and 
printer 1015 which connect to the PC 1004 through a USB 1017. Also, a 
digital camera 1020, a handheld PC (H/PC) 1021 and another personal 
computing device 1022 connect via an infrared port (IRDA) 1024, which 

20 also attaches to the PC 1004 through the USB 1017. Also, lighting 

switches 1030 and like home appliances are connected via an A/C power 
line-based networking 1032 to the PC 1002. Further, a chain of IEEE 
1 394 cables 1048 connect a digital TV 1040, DVD player 1041, digital 
video camcorder (DV/DVC) 1042, an audio device 1043 (e.g., CD 

25 player/recorder, radio receiver, amplifier, and like audio system 

component), and a game console 1044. Devices, such as a portable 



114 



WO 02/01833 PCT/US00/1 7844 



telephone 1050 and remote control 1051, have a radio frequency network 
connection with the PC 1004. 

With their various inter-networked connections, the embedded 
computing devices are "visible" and accessible from a client device 950 
5 (Figure 29) also connected to the computer network. 
Self-Install And Configure Of UPnP Bridge 

With reference now to Figure 41 , an instance of the UPnP bridge 
1 20 (Figure 2) is automatically installed and configured for a peripheral 
device by operating system software of a host computing platform in 

10 accordance with a process 1 100 upon attaching or connecting the 

peripheral to the host. In an implementation illustrated herein, this UPnP 
Bridge self-install and configure process 1 100 is implemented as an 
enhancement of the plug-and-play process of the Microsoft Windows 
operating system running on a personal computer. 

15 As per the conventional plug-and-play feature of the Microsoft 

Windows operating system, the host computer's operating system detects 
at action 1 102 as part of it boot-up routine that any new peripheral devices 
have been attached to a peripheral device bus (e.g., the ISA, EISA, PCI, 
USB, serial or parallel ports, etc.) of the host computer. Alternatively, this 

20 detecting of new peripheral devices can be done at any time during normal 
operation of the host computer so as to detect "hot-plugging" peripheral 
devices that can be attached to the host computer while running. Upon 
detecting a new peripheral device has been added, the host computer's 
operating system proceeds to identify and install an appropriate device 

25 driver software for the host operating system to interact with and/or 

control the peripheral device as indicated at action 1 103. If the appropriate 
device driver is not already loaded on the computer, the operating system 
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prompts the user to insert a disk or like storage medium containing the 
device driver. Alternatively, the operating system can download the device 
driver from a server computer on a network. If unable to identify the 
appropriate device driver for the new peripheral, the operating system 
5 prompts the user to select or provide the device driver (e.g., from a disk 
provided by the peripheral manufacturer). 

The enhanced plug-and-play feature of the operating system 
additionally automatically installs an instance of a UPnP Bridge 1 20 (Figure 
2) on the host computer at action 1 104 for use in adapting the peripheral 

10 for peer networking connectivity via the UPnP device control model over 
any networks connected to the host computer. The operating system 
configures this UPnP Bridge instance to expose the operational functions of 
the peripheral with an appropriate XML discovery and description data. As 
discussed above, any UPnP User Control Point thereafter can obtain the 

15 XML discovery and description data from the UPnP Bridge, and interact 
through the UPnP Bridge with the peripheral device as specified by the 
XML data. Alternatively, where an appropriate UPnP Bridge instance or 
configuring XML data is not available on the host computer, the operating 
system can prompt the user to select and/or provide such from a peripheral 

20 manufacturer-provided disk or download. 

The host's operating system then continues to repeat the actions 
1 102-1 104 for any other new peripheral devices that have been attached 
to the host computer. 

Although illustrated with reference to the Microsoft Windows 

25 operating system and a personal computer as the host, this self-install and 

♦ 

configuring of a peer networking-to-host/peripheral adapter also can be 
implemented on various other host/peripheral computing platforms (such as 
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in a video game consoles, television set-top boxes, audio-video consoles, 
etc., which are structured as host computers which are extensible by 
connecting peripheral devices) so as to automatically provide peer 
networking upon attaching a new peripheral to such computing platforms. 
5 Having described and illustrated the principles of our invention with 

reference to an illustrated embodiment, it will be recognized that the 
illustrated embodiment can be modified in arrangement and detail without 
departing from such principles. It should be understood that the programs, 
processes, or methods described herein are not related or limited to any 

10 particular type of computer apparatus, unless indicated otherwise. Various 
types of general purpose or specialized computer apparatus may be used 
with or perform operations in accordance with the teachings described 
herein. Elements of the illustrated embodiment shown in software may be 
implemented in hardware and vice versa. 

1 5 In view of the many possible embodiments to which the principles of 

our invention may be applied, it should be recognized that the detailed 
embodiments are illustrative only and should not be taken as limiting the 
scope of our invention. Rather, we claim as our invention all such 
embodiments as may come within the scope and spirit of the following 

20 claims and equivalents thereto. 
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We claim: 



1 . A distributed computing network having at least one 
computing device, the distributed computing network comprising: 

5 a plurality of peer networking computing devices communicating 

according to a peer networking connectivity model having user control 
points and controlled devices; 

at least some of said peer networking computing devices being 
programmed to operate as controlled devices exposing at least one 
10 operational function to control from others of said peer networking 
computing devices; 

at least some of said peer networking computing devices being 
programmed to operate as user control points whereat a user interface is 
presented for interaction by a user to control said controlled devices; 

1 5 at least one of said peer networking computing devices being a host 

computing device having a general purpose operating system that provides 
at least one service exposed to programmatic control via an operating 
system application programming interface, said host computing device 
further being programmed to expose said at least one service as a 

20 controlled device in said peer networking connectivity model. 

2. The distributed computing network of claim 1 further 
comprising a publishing adapter program running on said host computing 
device and operating to convert device control communications from said 

25 at least some peer networking computing devices operating as user control 
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points into calls via the operating system application programming interface 
for controlling, said at least one service. 

3. The distributed computing network of claim 2 wherein the 

5 publishing adapter program acts as a peer networking addressable device in 
the distributed network to which said at least some peer networking 
computing devices operating as user control points can establish a 
connection using an address identifying said peer networking addressable 
device. 

10 

4. The distributed computing network of claim 2 wherein the 
publishing adapter program supports discovery by said at least some peer 
networking computing devices operating as user control points of 
operational functions of said at least one service by supplying a structured 

1 5 data message defining control of said operational functions in response to a 
request according to the peer networking connectivity model from said at 
least some peer networking computing devices operating as user control 
points. 

20 5. The distributed computing network of claim 4 wherein the 

publishing adapter program supports control of said operational functions 
by said at least some peer networking computing devices operating as user 
control points by converting communications from said at least some peer 
networking computing devices operating as user control points as defined 

25 by the structured data message into communications via the operating 

system application programming interface exposing the at least one service 
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I 

for controlling said operational functions of said at least one peripheral 
device. 

6. A general purpose computer comprising: 

5 a processor, data storage, data input/output, and networking 

hardware resources; 

a general purpose operating system controlling the allocation and 
usage of the hardware resources; 

a plurality of services of the general purpose operating system 
10 operating to perform specific system functions to support application 
programs run on the computer; 

an application programming interface exposing the services to 
control from the application programs; 

a networking adapter and network operating software module for 
1 5 peer networking with peer devices; and 

a service remoting publisher software module operating to convert 
between communications according to a peer networking connectivity- 
based device control protocol and communications via the application 
programming interface with the services for exposing the services to 
20 control from the peer devices using the peer networking connectivity-based 
device control protocol. 

7. The general purpose computer of claim 6 wherein said service 
remoting publisher software module further converts between 

25 communications according to said protocol and application programming 
interface for also supporting control by the service of the peer devices 
using the peer networking connectivity-based device control protocol. 
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8. In a computing network, a method of interoperating between 
peer networking devices using a networking device control protocol and a 
service of a general purpose operating system on a computer exposed via 

5 an application programming interface, the method comprising: 

providing a peer networking address for addressing a peripheral 
device; 

in response to a request according to the networking device control 
protocol from a peer networking device specifying the peer networking 
1 0 address, establishing a connection with the peer networking device; and 

in response to invocation of an operational function of the service 
according to the networking device control protocol from the peer 
networking device on the connection, converting the invocation into a 
service invocation through the application programming interface to the 
1 5 service. 

9. The method of claim 8 further comprising: 
in response to a discovery request according to the networking 

device control protocol from the peer networking device, providing a 
structured data message defining invocation of at least one operational 
function of the service according to the networking device control protocol. 

10. The method of claim 9 wherein said invocation includes 
exchanging a set of further structured data format messages. 

11. A computer-readable data-carrying medium having a software 
program encoded thereon and executable on a general purpose computer in 
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a distributed network of peer computing devices for remotely exposing 
system functions of an operating system service available via an 
application programming interface to remote control via a device control 
protocol using peer networking connectivity, the device control protocol 
5 defining communications between user control point nodes and controlled 
device nodes in a distributed network of computing devices permitting 
control of operational functions and services of the controlled device nodes 
from the user control point nodes, the software program comprising: 
a program module for creating a peer-networking addressable 

10 controlled device node exposing the system function of the service 
available through the application programming interface; and 

a program module for converting communications to the peer- 
networking addressable controlled device node in the first device control 
protocol from a peer computing device to the general purpose computer 

1 5 into invocation of the service via the application programming interface. 

1 2. The computer-readable data-carrying medium of claim 1 1 
further comprising: 

a program module for creating a peer-networking addressable user 
20 control point node; and 

a program module for converting service invocations via the 
application programming interface on the general purpose computer into 
communications in the first device control protocol from the peer- 
networking addressable user control point node to control operational 
25 functions or services of another controlled device node. 
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13. The computer-readable data-carrying medium of claim 1 1 
further comprising a program module for providing structured data defining 
communications in the first device control protocol for invoking the system 
function of the service to user control points via the first device control 

5 protocol. 

14. A computer-readable data-carrying medium having a software 
program encoded thereon and executable on a computer in a distributed 
network of peer computing devices for device control of an operating 

10 system service on the computer, the software program comprising: 

a service remoter code acting to control functionality of the service 
via an application programming interface associated with the service; 

peer networking device control protocol code acting to interconnect 
with the peer computing devices to exchange device control 
1 5 communication for control of peer controlled devices by peer user control 
devices according to a peer networking device control protocol; and 

a peer networking device control protocol publishing service code 
communicating with the peer computing devices via the peer networking 
device control protocol code and with the service via the service remoter 
20 code and acting to expose the service's functionality as a peer controlled 
device according to the peer networking device control protocol to the peer 
computing devices to enable control of the peripheral device from the peer 
computing devices. 

25 1 5. A computer-readable data-carrying medium having a software 

program encoded thereon and executable on a computing device in a 
distributed network of peer computing devices interoperable according to a 
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peer networking device control protocol by which a user control point 
module on a controlling device operationally controls a controlled device, 
the software program comprising: 

peer networking connectivity services interacting with the peer 
5 computing devices using the peer networking device control protocol; 

peer networking connectivity publishing code converting the 
interaction with the peer computing devices using the peer networking 
device control protocol to operating system service invocations according 
to an operating system application programming interface; and 
10 an application programming interface operationally invoking a system 

function provided by an operating system service with the invocations. 

16. A computer-readable data-carrying medium having a software 
program encoded thereon and executable on a computing device in a 
1 5 distributed network of peer computing devices, the software program 
comprising: 

a controlled device operating system service remoter node operating 
as an addressable peer controlled device according to a peer networking 
device control- protocol defining communications between peer controlling 
20 devices and peer controlled devices permitting control of the peer 

controlled devices by the peer controlling devices on a peer networking 
basis; 

code in the controlled device operating system service remoter node 
operating responsive to control communications from a peer controlling 
25 device according to the peer networking device control protocol to control 
an operating system service via an operating system application 
programming interface. 
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17. A computer in a distributed computing network having a 
plurality of peer networking connected computing devices interoperating 
according to a peer networking device control model in which the peer 

• 5 networking connected computing devices run user control point modules 
and controlled device modules, where the user control point modules 
support user interaction to control operational functions supported by the 
controlled device modules, the computer having a general purpose 
operating system software loaded thereon comprising: 

10 a peer networking module for networking with the peer networking 

connected computing devices; 

a controlled device module supporting control from the user control 
point modules on the peer networking connected computing devices, and 
controlling services of the computer's general purpose operating system via 

15 an operating system application programming interface. 
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FIG. 2 
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<?xml version="1.0"?> 
<scpd xmlns='*-schema:scpdl-sdiema.xrrir> 
<service StateTable> 
<stateVariable> 

<name>currentChannel</name> 
<dataType>number</dataType> 
<allowedValueRange> 
<minimum>0</minimum> 
<maximum>55</maximum> 
<step>1</step> 
</allowedValueRange> 
</stateVariable> 
</se rvice Sta teTa b le> 



<actionList> 
<action> 

<name>ChannelUp</name> 
</action> 

<action> 

<name>ChannelDown</name> 
</action> 

<action> 

<name>SetChannel</name> 
<argument> 

<name>newChannel</name> 
<relatedStateVariable> 
currentChannel 
</relatedStateVariable> 
</argument> 
</action> 
</actionList> 
</scpd> 
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<?xml version="1.0 M ?> 
<Schema name- 'upnp^scpdl" 

xmlns= ,, urn:schemas-microsoft-com:xm!-data" 

xmlns:dt="urn:schemas-microsoft-com:datatypes ,, > 

<!- Common Elements and Attributes ~> 

<ElementType name="name" content= n textOn!y" dt:type="string" /> 
<!- Service State Table — >" 

<ElementType name= M minimum" content= M textOnly M dt:type="number" /> 
<ElementType name="maximum" content="textOnly" dt:type= M number" /> 
<ElementType name="step M content="textOnIy" dt:type="number" /> 

<ElementType name= M allowedValueRange M content= M eltOnly" modeN"cIosed"> 

<element type- 'minimum" /> 

<element type="maximum" /> 

<element type- 'step" minOccurs- 'O" /> 
</ElementType> 

<ElementType name="allowedValue" content="textOnly" /> 

<E!ementType name="allowedValueList M content="eltOnly" model="closed"> 

<element type="allowedValue" minOccurs="1 M maxOocurs="*" /> 
</ElementType> 

<ElementType name="dataType" content="textOnly" dt:type="string M /> 

<ElementType name="stateVariable" content="eltOnly" model="closed"> 
<element type="name" /> 
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<element type-'dataType" /> 

<group minOccurs= ,, 0" maxOccurs= M 1" order="one"> 

<element type="allowedValueRange" /> 

<element type="allowedValueLisr /> 
</group> 
</ElementType> 

■ 

i 

<ElementType name= n deviceStateTable M content= n eltOnly" model="closed"> 

<element type="stateVariable" minOccurs^T' maxOccurs= ,, *' , /> 
</ElementType> 



<!- Action List -> 

<ElementType name="relatedStateVariable" content= M textOnly" dt:type="string" /> 

<ElementType name= M argument" content="eltOnly" model= M closed"> 

<element type="name n /> 

<element type="relatedStateVariable M /> 
</ElementType> 

<ElementType name="action M content="eltOnly" model="closed"> 
<element type="name n /> 

<element type="argument" minOccurs= ,, 0" maxOccurs="*" /> 
</ElementType> 

<ElementType name="actionList" content="eltOnly n model="closed"> 

<element type="action" minOccurs^'O" maxOccurs="*" /> 
</ElementType> 

<!- Root Element ~> 

«- 

<ElementType name= ,, dcpd" content="eltOnly" model="closed M > 

<element type="deviceStateTable M /> 

<element type^'actionList" /> 
</ElementType> 
</Schema> 
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[ 

object, 

uuid(<foo>), 

dual, 

helpstring("IUPNPDevice interface"), 

pointer_default(unique) 

] 

interface lUPNPDevice : IDispatch f 

{ 

[propget, id(DISPID_UPNPDEVICE_DESCRIPTIONOOCUMENT) ? 
helpstring("returns the document from which the properties of this device are 
being read")] 

HRESULT DescriptionDocumentftrestricted, hidden, out, retval] 
lUPNPDescriptionDocument ** ppuddDocument); 

purpose: returns the document from which the properties of this device are 
being read. 

parameters: ppuddDocument, A reference to the description document 
object from which data about the device is being read. This must be freed when no 
longer needed. 

return values: S_OK, ppuddDocument is a refernce to the device's 
description document. 

[propget, id(DISPIDJJPNPDEVICEJSROOTDEVICE), 

helpstring("denotes whether the physical location information of this device can 
be set")] 

HRESULT lsRootDevice([out, retval] VARIANT_BOOL * pvarb); 

parameters: pvarb, the address of a VARIANT_BOOL that will receive the 
value of VARIANTJTRUE if the current device is the topmost device in the device 
tree, and will receive the value of VARIANT_FALSE otherwise, 
return values: S_OK, varb is set to the appropriate value 
note: if a device is a root device, calls RootDevice() or ParentDevice() will 
return NULL 



[propget, id(DISPIDJJPNPDEVICE_ROOT), 
helpstring("returns the top device in the device tree")] 
HRESULT RootDevice([out, retval] lUPNPDevice ** ppudDeviceRoot); 
purpose: returns the top device in the device tree 
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parameters: ppudDeviceRoot, On return, this refers to the "root" device of 
the current device tree. The root device is the topmost parent of the current device. 
If the current device is the root device this method will set *ppudDeviceRoot to null, 
and return S_FALSE. 

return values: S_OK, *ppudDeviceRoot contains a reference to the root 
device. S_FALSE, the current device is the root device. *ppudDeviceRoot is null. 

[propget, id(DISPID_UPNPDEVICE_PARENT), 
helpstringf'returns the parent of the current device")] 
HRESULT ParentDevice(fout, retval] lUPNPDevice ** ppudDeviceParent); 

parameters: ppudDeviceParent, On return, if the device has a parent, this is 
the address of a lUPNPDevice object which can describe the parent. This must be 
released when no longer needed. If the device has no parent (it is a "root" device), 
than this value will be set to null. 

return values: S__OK, ppudDeviceParent contains a reference to the device's 
parent. S_FALSE, the current devicfe is the root device, which has no parent. 
*ppudDeviceRoot is null. 

[propget, id(DISPIDJJPNPDEVICE_CHILDREN), 
helpstringfreturns a collection of the children of the current device")] 
HRESULT Children([out, retval] lUPNPDevices ** ppudChildren); 

parameters: ppudChildren, On return, this is the address of a newly-created 
lUPNPDevices collection that can enumerate this device's children. This must be 
released when no longer needed. If the device has no children, this method will 
return a collection object with a length of zero. 

return values: SJDK, ppudChildren contains a list of the device's children. 

[propget, id(DISPID_UPNPDEVICEJJDN), 

helpstringf'retums the UDN of the device'*)] 

HRESULT UniqueDeviceName([out, retval] BSTR * pbstrUDN); 

parameters: pbstrUDN, On return, this contains the address of a newly- 
allocated string which contains the device's Unique Device Name (UDN). The UDN 
is globally unique across all devices - no two devices will ever have the same UDN. 
This value must be freed when no longer needed. 

return values: S_OK pbstrUDN contains the UDN of the device 
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* * • 

[propget, id(DISPIDJJPNPDEVICE_DISPLAYNAME), 

helpstring("returns the (optional) display name of the device")] 
HRESULT Display Name([out, retval] BSTR * pbstrDisplayName); 

parameters: pbstrDisplayName, On return, this contains the address of the 
device's display name. This value must be freed when no longer needed. If the 
device does not specify a display name, this parameter will be set to null. 

return values: S_OK, bstrDisplayName contaips the display name of the 
device. pbstrDisplayName must be freed. S_FALSE, the device did not specify a 
display name. *pbstrDisplayName is set to null. 

note: it is possible for multiple devices to have the same display name. 
Applications should use UniqueDeviceName() to determine if two device objects 
refer to the same device. 

[propget, id(DISPID_UPNPDEVICE_CANSETDISPLAYNAME), 
helpstring("denotes whether the physical location information of this device can 
beset")] 

HRESULT CanSetDisplayName([out, retval] VARIANT_BOOL * pvarb); 

parameters: pvarb, the address of a VARIANT_BOOL This is true (!=0) on 
return when the device's display name can be set (via SetDisplayName) 
return values: S__pK varb is set to the appropriate value 

[id(DISPID_UPNPDEVICE_SETDISPLAYNAME), 
helpstring("sets the display name on the device")] 
HRESULT SetDisplayName([in] BSTR bstrDisplayName); 

parameters: bstrDisplayName, the value to set the device's display name to. 
return values: S_OK, varb is set to the appropriate value, 
note: On success, this method sets the display name used by a device. 
Note that this method changes the display name on the device itself, not simply on 
the local object. This will block while the name is being set. 

Additionally, this change will be made on the device alone, and will not be reflected 
in the current device object. After a successful call to this method, DisplayName 
will continue to return the 'old* value). To read the device's current name, the caller 
must re-load the device's description. 

[propget, id(DISPIDJJPNPDEVICE_DEVICETYPE), 



\ 



WO 02/01833 



PCT/US00/17844 



31/41 



FIG. 33 



helpstringfreturns the device type URI")] 

HRESULT Type([out, retvai] BSTR * pbstrType); 

parameters: pbstrType, On return, this contains the address of a newly-allocated 
string containing the device's type URI. This value must be freed when no longer 
needed. 

return values: S_OK, bstrType contains the type URI of the device, and must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICE_SERVICES), 
helpstringfreturns the collection of services exposed by the device")] 
HRESULT Services([out, retvai] lUPNPServices ** ppusServices); 

parameters: ppusServices, On return, this is the address of a newly-created 
lUPNPServices collection that can enumerate the services exposed by the device. 
This must be released when no longer needed. If the device exposes no services, this 
method will return a collection object with a length of zero. 

return values: S_OK, pusServices contains a list of the device's children. 

[propget, id(DISPID_UPNPDEVICE_SERVICEIDENTIFIER), 
helpstring( M returns the (optional) service identifier of the device")] 
HRESULT Serviceldentifier([out, retvai] BSTR * pbstrServicelD ); 

parameters: pbstrServicelD, On return, this contains the address of a newly- 
allocated string containing the contents of the device's Serviceldentifier element, if the 
device specifies one. This value must be freed when no longer needed. If the device 
does not specify a Serviceldentifier value, this parameter will be set to null. 

return value: S_OK, bstrServicelD contains the service identifier of the device. 
pbstrServicelD must be freed. S_FALSE, the device did not specify a service identifier. 
*pbstrServicelD is set to null. 

note having a Serviceldentifier is mutually exclusive with having services. Any 
device will either have a list of services or a Serviceldentifier, but not both. 

[id(DISPID_UPNPDEVICEDESCRIPTION_LOADSMALLICON), 
helpstring("loads a small (titlebar-sized) icon representing the device, encoded in the 

specified format")] 

HRESULT LoadSmalllcon([in] BSTR bstrEncodingFormat, 
[out, retvai] BSTR * pbstrlconURL); 
parameters: 
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bstrEncodingFormat, A string containing the mime-type representing the desired 
encoding format of the icon. pbstrlconURL, On return, *pbstrlconURL contains a 
newly-allocated string representing the URL from which the icon can be loaded. 
This string must be freed when no longer needed. 

return values: SJDK, *pbstrlconURL contains a reference to an icon, 
encoded in the desired encoding format. 

[id(DISPID_UPNPDEVICEDESCRIPTION_LOADICON), 
helpstring("loads a standard-sized icon representing the device, encoded in the 
specified format")] 

HRESULT Loadlcon([in] BSTR bstrEncodingFormat, 
[out, retval] BSTR * pbstrlconURL); 

parameters: bstrEncodingFormat, A string containing the mime-type 
representing the desired encoding format of the icon. pbstrlconURL, On return, 
*pbstrlconURL contains a newly-allocated string representing the URL from which 
the icon can be loaded. This string must be freed when no longer needed. 

return values: S_OK, *pbstrlcohURL contains a reference to an icon, 
encoded in the desired encoding format. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_PRESENTATIONURL), 
helpstringfobtains a presentation URL to a web page that can control the 
device")] 

HRESULT PresentationURL([out, retval] BSTR * pbstrURL); 

parameters: pbstrURL, on return, the address of a newly-allocated string 
containing the web-page-based control URL. If the device did not specify a 
presentation URL, an empy string ("") will be returned. 

return values:S_OK, bstrURL contains a newly-allocated URL that must be 
freed when no longer needed. S_FALSE, the device does not have a presentation 
URL. pbstrURL is set to null. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_PHYSICALLOCATION), 
helpstring("a set of properties describing the device's physical location")] 
HRESULT PhysicalLocation([out, retval] lUPNPPropertyBag * pupl); 
parameters: pupl on return, the address of a newly-allocated 
UPNPPropertyBag object which contains information about the device's physical 
location 

return values 
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S_OK upl contains a newly-allocated object that the caller must free when it 
is no longer needed. 

note: if the object does not provide any description information, an empy 
property bag will be returned. See SetPhysicalLocation for a listing of defined 
values in a physical location property bag. 

[propget, 

id(DISPID_UPNPDEVICEDESCRIPTION_CANSETPHYSICALLOCATION), 

helpstringfdenotes whether the physical location information of this device<:an 
be set")] 

HRESULT CanSetPhysicalLocation([out, retval] VARIANTJ300L * pvarb); 

parameters: pvarb the address of a VARIANTJ300L. This is true (NO) on 
return when the device's physical location can be set (via SetPhysicalLocation) 
return values: SJDK varb is set to the appropriate value 

[id(DISPID_UPNPDEVICEDESCRIPTION_SETPHYSICALLOCATION) 4 
helpstring("writes a set of properties describing the device's physical location to 
the device")] 

HRESULT SetPhysicalLocation([in] lUPNPPropertyBag * pupl); 

parameters: pupl A UPNPPropertyBag object which contains the name- 
value pairs representing the device's current location, the function will not free the 
object. 

return values: S_OK he device has been updated with the supplied 
physical location information 

note: the following are standard values in the physical location property bag: 
country, campus, building, floor, wing, room, latitude, longitude, altitude. These 
values can be used programmatically to implement sorting or filtering functionality 
based on the device's location. Additionally the property bag supports the following 
value: description, which contains a user-displayable string representing a device's 
location which does not have programattic significance. Additionally, the physical 
location update will be made on the device alone, and will not be reflected in the 
current device object. After a successful call to this method, PhysicalLocation will 
continue to return the 'old' value. To read the device's current name, the caller 
must re-load the device's description. 

> 
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• * * 

[propget, id(DISPID_UPNPDEVICEDESCRIPT!ON_PRODUCTNAME), 
helpstring("a displayable string containing the product name")] 
HRESULT ProductName([out, retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newly-allocated string 
containing the product name of the device. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

R 

J 

[propget id(DISPID_UPNPDEVICEDESCRIPTION_DESCRIPTION), 
helpstringfdisplayable summary of the device's function")] 
HRESULT Description([out, retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newly-allocated string 
containing a short description of the device meaningful to the user. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_MODELNAME), 
helpstring("displayable model name")] 
HRESULT ModelName([out, retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newly-allocated string 
containing the manufactuer's model name of the device. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_SERIALNUMBER), 
helpstringfdisplayable serial number")] 
HRESULT Serial Number([out, retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newly-allocated string 
containing the manufacturers serial number of the device. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

note: a device's serial number is not guaranteed to be globally unique. The 
DeviceUniqueName should always be used to distinguish devices. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_MANUFACTURERNAME), 
helpstring( M displayable manufacturer name")] 
HRESULT ManufacturerName([out, retval] BSTR * pbstr); 
parameters 
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pbstr, on return, the address of a newly-allocated string containing the name of the 
device's manufactuer. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_MANUFACTURERURL) l 
helpstring("URL to the manufacturer's website")] 
HRESULT ManufacturerURL([out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated string 
containing the URL of the manufacturer's website. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_MODELNAME), 
helpstring("displayable model name")] 
HRESULT ModelName([out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated string 
containing the manufactuer's model name for the device. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_SUPPORTLIST), 
helpstring("technical support contact information")] 
HRESULT SupportList([out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated, multi-line 
string containing phone numbers and other information that can guide the user to 
technical support. This string must be freed when no longer needed. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_FAQLIST), 
helpstring("FAQ access display information")] 
HRESULT FAQList([out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated, multi-line 
string containing FAQ information that can provide the user with URLs at which 
device FAQs may be located. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 
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[propget, id(DISPID_UPNPDEVICEDESCRIPTION_UPDATELIST), 

helpstringfinformation explaining where the user can update the device's 
firmware")] 

HRESULT UpdateList([out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated, multi-line 
string containing information and URU from which the user can download updates 
for the device's firmware. 

■ 

return values: S_OK, pbstr contains a newly-aljocated string that must be 
freed when no longer needed. 
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[ 

object, 

uuid(FDBC0C73-BDA3-4C66-AC4F-F2D96FDAD68C), 
dual, 

helpstring("IUPNPDevices Interface"), 
pointer_def a u lt( u n iq ue) 

] 

lUPNPPropertyBag 
{ 

[propget, id(DISPID_UPNP_PROPERTYBAG_READ), 
helpstring("reads a value from the property bag")] 

HRESULT Read([in] BSTR bstrName, [out, retval] VARIANT * pvarResult); 
parameters: bstrName, name of the property to read, case is ignored. 
pvarResultvalue of the property, if the property doese not exist, this is of type 
VT_EMPTY 

return values: S_OK, the value was found in the property bag, and returned 
in pvarResult. S_FALSE, there was no value with the given name in the property 
bag. *pvarResult is of type VT EMPTY 

[propget, id(DISPIDJJPNP j^ROPERTYBAGJ/VRITE), 
helpstring( M writes a value to the property bag")] 
HRESULT Write([in] BSTR bstrName, [in] VARIANT * pvarValue); 

parameters: bstrName, name of the property to write, case is preserved 
when writing. The supplied value will replace any other values of the same name, 
even if they differ in case. pvarValue, value of the property to write. 

return values: S_OK, the value was written to the property bag, replacing the 
value currently associated with this property, if it existed. 

[propget, id(DISPIDJJPNPJPROPERTYBAG_DELETE), 
helpstring("removes a value from the property bag")] 
HRESULT Delete([in] BSTR bstrName); 

parameters: bstrName, name of the value to remove from the property gab. 
case is ignored when finding a value to remove. 

return values: S_OK, the value has been removed from the property bag. 
S__FALSE, the value was not found in the property bag. 

}; 
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FIG. 40 



[ 

object, 

uuid(A29501 9C-DC65-47DD-90DC-7FE91 8A1 AB44), 
dual, 

helpstring("IUPNPService Interface"), 

pointer_default(unique) 

] 

interface lUPNPService : IDispatch 
{ 

[id(1), helpstring( M method GetProperty")] 
HRESULT GetProperty( 
[in] BSTR bstrPropertyName, 
[out, retval] VARIANT *pValue 

); 

[id(2), heipstringfmethod InvokeAction")] 
HRESULT lnvokeAction( 
[in] BSTR bstrActionName, 
[in] VARIANT saActionArgs, 
[out, retval] long *plStatus 

); 

[propget, id(3), helpstring("property DCPI")] 
HRESULT DCPI( 
[out, retval] BSTR *pVal 

); 



[propget, id(4), 

helpstring("returns a manufactuer-defined extension property")] 
HRESULT VendorExtension([out, retval] VARIANT * pvarValue ); 

parameters: pvarValueOn return, this variant is filled with the value of the 
"extension" element. If none exists, pvarValue is set to VT_JEMPTY 

return values: S_OK, varValue is set to the extension element. S_FALSE, 
no vendor extension element exists. pvarValue is VT EMPTY 
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FIG. 41 
[ 

object, 

uuid(FDBC0C73-BDA3-4C66-AC4F-F2D96FDAD68C), 
dual, 

helpstringflUPNPDevices Interface"), 
pointer_default(unique) 

] 

interface lUPNPDevices : IDispatch 

{ 

[propget, id(1). helpstringfproperty Count")] 
HRESULT Count( 
[out, retval] long *pVal 

); 

[propget, id(DISPID_NEWENUM), helpstringfproperty _NewEnum")] 

HRESULT _NewEnum( 

[out, retval] LPUNKNOWN *pVal 

); 

[propget, id(DISPID_VALUE), helpstringfproperty Item")] 

HRESULT ltem( 

[in] long llndex, 

[out, retval] VARIANT *pVal 

); 
}; 
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FIG. 42 
[ 

object, 

uuid(3F8C8E9E-9A7A-4DC8-BC41-FF31FA374956), 
dual, 

helpstring("IUPNPServices Interface"), 
pointer_default(unique) 

] 

interface lUPNPServices : IDispatch 
{ 

[propget, id(1), helpstring("property Count")] 1 
HRESULT Count( 
[out, retval] long *pVal 

); 

[propget, id(DISPID_NEWENUM), helpstring("property _NewEnum")] 

HRESULT _NewEnum( 

[out, retval] LPUNKNOWN *pVal 

); 

[propget, id(DISPID_VALUE), helpstring("property Item")] 

HRESULT ltem( 

[in] long llndex, 

[out, retval] VARIANT *pVal 

); 
}; 
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FIG. 43 
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